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 Pylearn2/
python ./doc/scripts/docgen.py
If you don’t want to generate the pdf, do the following:
cd Pylearn2/
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
- 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)
Link to the generated doc of a function this way:
:func:`perform`
For example:
of the :func:`perform` function.
Link to the generated doc of a class this way:
:class:`RopLop_checker`
For example:
The class :class:`RopLop_checker`, give the functions
However, if the link target is ambiguous, Sphinx will generate warning or errors.
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.
The server that hosts the pylearn2 documentation runs a cron job roughly every 2 hours that fetches a fresh Pylearn2 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 pylearn-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).
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 the scripts ~/nightly_build/do_nightly_build_{theano,pylearn,deeplearning}. These scripts perform an update of theano (and pylearn, and DeepLearningTutorials too), and executes nose (in various settings).
The output is emailed automatically to the theano-buildbot mailing list.
There is other stuff to document here, e.g.:
- We also want examples of good documentation, to show people how to write ReST.