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/

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

cd PyTensor/
python ./doc/scripts/ --nopdf

For more details:

$ python doc/scripts/ --help
Usage: doc/scripts/ [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 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.