.. _documentation_development: Documentation Development Guide =============================== :Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna :Last Updated: $Date: 2011-08-11 16:22:08 +0000 (Thu, 11 Aug 2011) $ .. contents:: Table of Contents :depth: 2 :backlinks: top Background ---------- The current structure of the ZOO Project documentation process is for developers with :ref:`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:** #. install `Python 2.X `__ #. download `setuptools `__ #. make sure that the ``C:/Python2X/Scripts`` directory is your path #. 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. #. install `MiKTeX `__ if you want to build pdfs #. checkout the /docs directory from SVN, such as: :: svn checkout http://svn.zoo-project.org/svn/trunk zoo-project #. inside the /docs directory, execute: :: make html or :: make latex the HTML output will be written to the _build/html sub-directory. **On Linux:** #. 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 #. install sphinx using easy_install: :: sudo easy_install Sphinx .. note:: Make sure you install Sphinx 1.0 or more recent. See note above. #. checkout the /docs directory from SVN, such as: :: svn checkout http://svn.zoo-project.org/svn/trunk zoo-project #. 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:** #. install sphinx using easy_install: :: sudo easy_install Sphinx .. note:: Make sure you install Sphinx 1.0 or more recent. See note above. #. install `MacTex `__ if you want to build pdfs #. checkout the /docs directory from SVN, such as: :: svn checkout http://svn.zoo-project.org/svn/trunk zoo-project #. 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.