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
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
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.
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.
$ sudo apt-get install graphviz
Install Sphinx (latest version):
$ sudo easy_install -U Sphinx
(Optional) Install rst2pdf:
$ sudo easy_install -U rst2pdf
(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
Checkout a copy of the documentation from subversion:
$ svn co https://repository.dataone.org/documents/Projects/cicore/architecture/api-documentation
Build the documents:
$ cd api-documentation $ make html
The documents will be available in
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.
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.
To build an ePub version of the documents:
$ make epub