About These Documents
=====================

These documents are generated using Sphinx_ for the overall document
processing and generation, and PlantUML_ for most of the UML diagrams.


Editing Content
---------------

All of these documents are formatted in reStructuredText_, formatted plain
text that is similar to the plain text formatting used in wiki pages. The
formatting guidelines for Sphinx are available at
http://sphinx.pocoo.org/contents.html

Portions of content, specifically all the individual function and exception
descriptions, are maintained in an Excel spreadsheet (best edited using
OpenOffice Calc). The reStructuredText_ descriptions of the methods and
exceptions is generated by processing the content in the spreadsheet with a
python script "ihwd.py" located in the tools folder.

All content should be saved as UTF-8 encoded text using UNIX® style new lines.
White space and indentation is part of the formatting for reStructuredText.
Please be consistent with the use of soft tabs (2 spaces per tab).

reStructuredText_ can be edited with any plain text editor. These documents
have been edited mainly with TextMate_ on OS X, which offers a preview feature
when the `reStructuredText bundle`_ is installed. Other editors that work well
for editing reStructuredText_ are jEdit and Komodo Edit. There are also
various plugins available for editors to assist with reStructuredText
formatting.

Follow the normal procedures for working with the subversion repository. After
checking in, your edits should appear in the `built out version`_ of the docs
within five minutes.

The convention for different levels of heading used in these documents is::

  ===  Level 1
  ---  Level 2
  ~~~  Level 3
  ...  Level 4


Building the Documentation
--------------------------

Sphinx_ is required to build the design documents from the source. A couple of
Sphinx extensions are included with the subversion checkout of these documents
(in ``tools/docutils/rst_directives``). Portions of Sphinx and the PlantUML_
extension have a dependency of Graphviz_, and this will need to be installed
in order to build the documents. The rst2pdf_ library is required to build the pdf version of the documents.

Setting up a Build Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following general instructions apply for Ubuntu linux. Adjust the commands
as necessary for your OS (and please update these docs to help others in the
process). It is assumed that Python >= 2.6 and Java are available.

1. Install graphviz::

     $ sudo apt-get install graphviz

2. Install Sphinx (latest version)::

     $ sudo easy_install -U Sphinx

3. (Optional) Install rst2pdf::

     $ sudo easy_install -U rst2pdf

4. (Optional) Edits to the method descriptions in the excel spreadsheet
   (``MethodCrossReference.xls``) require regeneration of some portions of the
   documentation, which requires a couple of Python libraries (xlrd and xlwt)::

     $ sudo easy_install xlrd xlwt


5. Checkout a copy of the documentation from subversion::

     $ svn co https://repository.dataone.org/documents/Projects/cicore/architecture/api-documentation


6. Build the documents::

     $ cd api-documentation
     $ make html

   The documents will be available in ``build/html``, with ``index.html`` being the root document.

* If changes are made to ``MethodCrossReference.xls``, then an additional make
  step is required::

       $ cd api-documentation
       $ make generate
       $ make html

* If changes to plantuml diagrams have been made then it will be necessary to
  regenerate the associated .png images. This can be done using *make*::

       $ cd api-documentation
       $ make plantuml
       $ make html

  The plantuml diagram generation can take a while. There are three sub-tasks
  for *make*, plantuml_source, plantuml_usecase, and plantuml_types which can
  be used to build diagrams under the *source/design*,
  *source/design/UseCases*, or *source/apis* folders respectively.

7. To build a PDF version of the documents.::

     $ make pdf

   Note that the PDF generator can be quite fickle, and may require some tweaking to work.

8. To build an ePub version of the documents::

     $ make epub



.. _Graphviz: http://www.graphviz.org/

.. _Sphinx: http://sphinx.pocoo.org/

.. _PlantUML: http://plantuml.sourceforge.net

.. _xlrd: http://pypi.python.org/pypi/xlrd

.. _setuptools: http://pypi.python.org/pypi/setuptools

.. _rst2pdf: http://code.google.com/p/rst2pdf/

.. _built out version: http://129.24.0.15/ArchitectureDocs/

.. _TextMate: http://macromates.com/

.. _reStructuredText bundle: https://github.com/textmate/restructuredtext.tmbundle

.. _jEdit: http://www.jedit.org/

.. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html