Documentation Development Guide

Authors:Nicolas Bozon, Gérald Fenoy, Jeff McKenna Last Updated:$Date: 2011-12-07 14:19:47 +0100 (Wed, 07 Dec 2011) $

Table of Contents

• Documentation Development Guide
  • Background
  • reStructuredText Reference Guides
  • reStructuredText Formatting
  • Installing and Using Sphinx for rst-html Generation

Background

The current structure of the ZOO Project documentation process is for developers with SVN commit access to maintain their documents in reStructuredText format, and therefore all documents live in the /docs directory in SVN. The Sphinx documentation generator is used to convert the reStructuredText files to html, and the live website is then updated on an hourly basis.

reStructuredText Reference Guides

• Docutils Quick reStructuredText
• Docutils reStructuredText Directives
• Sphinx’s reStructuredText Primer
• search Sphinx’s mailing list

reStructuredText Formatting

• All text should be hard breaks at or around the 80 column mark, just as the source code.

Installing and Using Sphinx for rst-html Generation

Note

You can browse the versions of the Sphinx packages here, and then install the exact version such as:

easy_install Sphinx==1.0.7

On Windows:

1. install Python 2.X

2. download setuptools

3. make sure that the C:/Python2X/Scripts directory is your path

4. execute the following at commandline:

   easy_install Sphinx

   ...you should see message: “Finished processing dependencies for Sphinx”

   Note

   Make sure you install Sphinx 1.0 or more recent. See note above.

5. install MiKTeX if you want to build pdfs

6. checkout the /docs directory from SVN, such as:

   svn checkout http://svn.zoo-project.org/svn/trunk zoo-project

7. inside the /docs directory, execute:

   make html

   or

   make latex

   the HTML output will be written to the _build/html sub-directory.

On Linux:

1. make sure you have the Python dev and setuptools packages installed. On Ubuntu:

   sudo apt-get install python-dev
   sudo apt-get install python-setuptools

2. install sphinx using easy_install:

   sudo easy_install Sphinx

   Note

   Make sure you install Sphinx 1.0 or more recent. See note above.

3. checkout the /docs directory from SVN, such as:

   svn checkout http://svn.zoo-project.org/svn/trunk zoo-project

4. to process the docs, from the ZOO /docs directory, run:

   make html

   or

   make latex

   the HTML output will be written to the build/html sub-directory.

Note

If there are more than one translation, the above commands will automatically build all translations.

On Mac OS X:

1. install sphinx using easy_install:

   sudo easy_install Sphinx

   Note

   Make sure you install Sphinx 1.0 or more recent. See note above.

2. install MacTex if you want to build pdfs

3. checkout the /docs directory from SVN, such as:

   svn checkout http://svn.zoo-project.org/svn/trunk zoo-project

4. to process the docs, from the ZOO /docs directory, run:

   make html

   or

   make latex

   the HTML output will be written to the build/html sub-directory.