Let's say you are writing documentation, and want to see the `sphinx
<http://sphinx.pocoo.org/>`__ output before you push it.
The documentation will be generated in the ``html`` directory.
:api:`linkname <path-to-symbol>`
.. code-block:: bash
For example::
cd Theano/
python ./doc/scripts/docgen.py
:api:`function <theano.compile.function>`
If you don't want to generate the pdf, do the following:
You can also use ``:api:\`path-to-symbol\``` directly.
.. code-block:: bash
If you are lazy, you can try::
cd Theano/
python ./doc/scripts/docgen.py --nopdf
:api:`<function>`
However, if the link target is ambiguous, Sphinx will generate errors.
For more details:
NB the ``:api:`` reference is special magic by Olivier, in
./doc/scripts/docgen.py.
.. code-block:: bash
How to add TODO comments in Sphinx documentation
-------------------------------------------------
$ 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
To include a TODO comment in Sphinx documentation, use an indented block as
follows::
Use ReST for documentation
--------------------------
.. TODO: This is a comment.
.. You have to put .. at the beginning of every line :(
.. These lines should all be indented.
* :ref:`ReST <http://docutils.sourceforge.net/rst.html>` 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)
It will not appear in the output generated.
.. TODO: Check it out, this won't appear.
.. Nor will this.
How to link to class/function documentations
--------------------------------------------
How to write API documentation
---------------------------------------
Link to the generated doc of a function this way::
API documentation is processed by `epydoc
<http://epydoc.sourceforge.net/>`__ and should be written in
`reStructuredText <http://docutils.sourceforge.net/rst.html>`__. See `here
for details about how to use reST with epydoc documentation.
:func:`perform`
Use ReST for API and Sphinx documentation
-----------------------------------------
For example::
* 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)
of the :func:`perform` function.
How to build documentation
---------------------------------------
Link to the generated doc of a class this way::
Let's say you are writing documentation, and want to see
the `epydoc <http://epydoc.sourceforge.net/>`__ and `sphinx
<http://sphinx.pocoo.org/>`__ output before you push it.
:class:`RopLop_checker`
The following technique uses Olivier's code to insert :api: links:
For example::
.. code-block:: bash
The class :class:`RopLop_checker`, give the functions
cd Theano/
python ./doc/scripts/docgen.py
If you don't want to rerun epydoc, do the following:
However, if the link target is ambiguous, Sphinx will generate warning or errors.
.. code-block:: bash
cd Theano/
python ./doc/scripts/docgen.py --rst
How to add TODO comments in Sphinx documentation
-------------------------------------------------
To include a TODO comment in Sphinx documentation, use an indented block as
follows::
For more details:
.. TODO: This is a comment.
.. You have to put .. at the beginning of every line :(
.. These lines should all be indented.
.. code-block:: bash
It will not appear in the output generated.
$ 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
--epydoc: only compile the api documentation (requires epydoc)
--help: this help
.. TODO: Check it out, this won't appear.
.. Nor will this.
How documentation is built on deeplearning.net
...
...
@@ -107,7 +98,7 @@ 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@ (or Dumitru, or Fred directly).
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).
...
...
@@ -147,8 +138,5 @@ TO WRITE
*There is other stuff to document here, e.g.:*
* where the documentation is getting built, and epy.
* How epydoc and sphinx are integrated
* Explain the special magic in ./doc/scripts/docgen.py
* We also want examples of good documentation, to show people how to write sphinx,
* We also want examples of good documentation, to show people how to write ReST.
