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