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
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 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.