Documentation Development Guide

Authors:Nicolas Bozon, Gérald Fenoy, Jeff McKenna
Last Updated:$Date: 2015-02-25 13:23:00 +0100 (mer. 25 févr. 2015) $

License

The ZOO-Project documentation is released under the Creative Commons Attribution-ShareAlike 4.0 International Public License (CC-BY-SA). This license must be kept when editing or creating a new documentation file.

development/../../_static/images/by-sa.png

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 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.