Table Of Contents

Previous topic

2. Release Guidelines

Next topic

3.2.1. Create your own sphinx project

This Page

3. How to use sphinx ?

3.1. Introduction

Using Sphinx to generate Reference guide is not as straightforward as using a tool such as Epydoc but brings a much more flexible and powerful tool that allows us to create user guide and tutorials as well.

It uses the reST syntax, that is quite simple to learn and has the advantagse to be human readable (useful for the docstrings !) . Moreover, it comes with many plugins such as LaTeX that can be used for equations.

Here below we hope that you will find some helps to start with Sphinx.

First, you will need to install Sphinx, which is done very easily using easy_install:

easy_install -U sphinx

3.3. Compiling the documentation

Within OpenAlea/VPlants/Alinea, if you are working on a package that has already been setup for you and if you want to compile the documentation yourself (e.g., you want to update it), you have two methods:

3.3.1. From the package directory using setuptools

Go the root directory of the package and type:

python setup.py build_sphinx

The HTML outputs should be ready in ./doc/html. Similarly, you can have a LaTeX output as follows:

python setup.py build_sphinx -b latex

Note

Sphinx takes care to parse only the files that have changed. You may want to force the building using the -E option as follows:

python setup.py build_sphinx -E

3.3.2. From the ./doc directory using Makefile

Alternately, go in the ./doc/ directory and just type:

make html

or:

make latex

Warning

Exception, the openalea/doc directory is not yet a package, so only make html will work

3.4. Upload the documentation

If the build is successful and if you have an SSH key on the GForge, you may even upload the documentation to the wiki:

python setup.py sphinx_upload --username <your gforge username>

Note

setuptools will look in the setup.cfg file looking for project and package in the [upload_sphinx] section. (see next section)

Warning

Exception, the openalea/doc directory is not yet a package; In order to upload the documentation, use the script sphinx_upload.py that is present in ./openalea/doc.

3.5. How to initialise a new package

In principle the administrator should initialise the sphinx documentation once for all when the developers decide to release their package. If you still want to do it yourself, check this link:

3.6. Sphinx and reST syntax

It’s time to start writting documentation. Well, with Sphinx you will need to learn a new language, that is called reST for restructuredText. No worries, it is quite simple and you will get plenty of examples. Indeed, all those pages contains a link to the source code (see in the right sidebar), so it will be a good starting point.

Here are some links related to the sphinx syntax

Once you are familiar with reST, you can jump to your code to add documenation either directly in the docstrings of your python modules or inside the doc/user directory of your package using reST.

Note

Administrators may be interested in the following link that was used to test different type of doctring syntax

3.7. Administrators usage

Here below, you will find some extra information explaining the structures of the documentation on the wiki (administrator usage)

3.8. Authors

  • Thomas Cokelaer

3.9. ChangeLog

3.9.1. 0.8.0 release

  • Simplify the usage of sphinx * upload all released packages documentation on the webpage * update this documentation

3.9.2. 0.7.0 release

Add sphinx documentation:
  • common_conf.py
  • common.ini to be used by all packages (similar to the original conf.py file used by Sphinx
  • add the .templates directory that contains all the HTML templates (original from Sphinx, refactored in addition to a set of own templates)

3.9.3. 0.6.2 release