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