source: trunk/docs/development/documentation.txt @ 591

.. _documentation_development:

Documentation Development Guide
===============================

:Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna
:Last Updated: $Date: 2015-02-25 12:13:33 +0000 (Wed, 25 Feb 2015) $

.. contents:: Table of Contents
    :depth: 2
    :backlinks: top


License
-----------------

The ZOO-Project documentation is released under the
`Creative Commons Attribution-ShareAlike 4.0 International Public License <https://creativecommons.org/licenses/by-sa/4.0/legalcode>`__
(CC-BY-SA). This license must be kept when editing or creating a new documentation file.

.. image:: ../../_static/images/by-sa.png
   :target: https://creativecommons.org/licenses/by-sa/4.0/legalcode/
   :height: 31px
   :width: 88px


Background
----------

The current structure of the ZOO Project documentation process is for
developers with :ref:`SVN <svn>` commit access to maintain their documents
in reStructuredText format, and therefore all documents live in the
/docs directory in SVN.  The `Sphinx <http://sphinx.pocoo.org/>`__ 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 <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__
- Docutils `reStructuredText Directives <http://docutils.sourceforge.net/docs/ref/rst/directives.html>`__
- Sphinx's `reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`__
- search Sphinx's `mailing list <http://groups.google.com/group/sphinx-dev>`__

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 <http://pypi.python.org/pypi?%3Aaction=index>`__,
    and then install the exact version such as:
        
    ::
        
        easy_install Sphinx==1.0.7


**On Windows:**

#. install `Python 2.X <http://www.python.org/>`__
#. download `setuptools <http://pypi.python.org/pypi/setuptools#windows>`__
#. 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 <http://miktex.org>`__ 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 <http://www.tug.org/mactex/2009/>`__ 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.