Documentation Documentation AKA Meta-Documentation

How to build documentation

Let’s say you are writing documentation, and want to see the sphinx output before you push it. The documentation will be generated in the html directory.

cd Theano/
python ./doc/scripts/docgen.py

If you don’t want to generate the pdf, do the following:

cd Theano/
python ./doc/scripts/docgen.py --nopdf

For more details:

$ python doc/scripts/docgen.py --help
Usage: doc/scripts/docgen.py [OPTIONS]
  -o <dir>: output the html files in the specified dir
  --rst: only compile the doc (requires sphinx)
  --nopdf: do not produce a PDF file from the doc, only HTML
  --help: this help

Use ReST for documentation

  • ReST is standardized. epydoc is not. trac wiki-markup is not. This means that ReST can be cut-and-pasted between epydoc, code, other docs, and TRAC. This is a huge win!
  • ReST is extensible: we can write our own roles and directives to automatically link to WIKI, for example.
  • ReST has figure and table directives, and can be converted (using a standard tool) to latex documents.
  • No text documentation has good support for math rendering, but ReST is closest: it has three renderer-specific solutions (render latex, use latex to build images for html, use itex2mml to generate MathML)

How to add TODO comments in Sphinx documentation

To include a TODO comment in Sphinx documentation, use an indented block as follows:

.. TODO: This is a comment.
.. You have to put .. at the beginning of every line :(
.. These lines should all be indented.

It will not appear in the output generated.

How documentation is built on deeplearning.net

The server that hosts the theano documentation runs a cron job roughly every 2 hours that fetches a fresh Theano install (clone, not just pull) and executes the docgen.py script. It then over-writes the previous docs with the newly generated ones.

Note that the server will most definitely use a different version of sphinx than yours so formatting could be slightly off, or even wrong. If you’re getting unxpected results and/or the auto-build of the documentation seems broken, please contact theano-dev@.

In the future, we might go back to the system of auto-refresh on push (though that might increase the load of the server quite significantly).

pylint

pylint output is not autogenerated anymore.

Pylint documentation is generated using pylintrc file: Theano/doc/pylintrc

The nightly build/tests process

The user lisa runs a cronjob on the computer ceylon, this happens nightly. (To have the crontab executed, the lisa user must be logged into ceylon, Fred leaves a shell open for that.)

The cronjob executes a script that download/update the repo of Theano, Pylearn, Pylearn2 and the Deep Learning Tutorial, then run their tests script under */misc/do_nightly_build. Those script tests the project under various condition. The cron job also run some tests in Python 2.4 and Python 3.3 for Theano.

The output is emailed automatically to the theano-buildbot mailing list.

TO WRITE

There is other stuff to document here, e.g.:

  • We also want examples of good documentation, to show people how to write ReST.