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 PyTensor/
python ./doc/scripts/docgen.py

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

cd PyTensor/
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. trac wiki-markup is not. This means that ReST can be cut-and-pasted between 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 link to class/function documentations#

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.

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.