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
.. code-block:: bash
./doc/scripts/docgen.py.
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
Use ReST for documentation
follows::
--------------------------
.. TODO: This is a comment.
* :ref:`ReST <http://docutils.sourceforge.net/rst.html>` is standardized.
.. You have to put .. at the beginning of every line :(
epydoc is not. trac wiki-markup is not.
.. These lines should all be indented.
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.
How to link to class/function documentations
.. Nor will this.
--------------------------------------------
How to write API documentation
Link to the generated doc of a function this way::
---------------------------------------
API documentation is processed by `epydoc
:func:`perform`
<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.
Use ReST for API and Sphinx documentation
For example::
-----------------------------------------
* ReST is standardized. epydoc is not. trac wiki-markup is not.
of the :func:`perform` function.
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)
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
:class:`RopLop_checker`
the `epydoc <http://epydoc.sourceforge.net/>`__ and `sphinx
<http://sphinx.pocoo.org/>`__ output before you push it.
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/
How to add TODO comments in Sphinx documentation
python ./doc/scripts/docgen.py --rst
-------------------------------------------------
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
.. TODO: Check it out, this won't appear.
Usage: doc/scripts/docgen.py [OPTIONS]
.. Nor will this.
-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
How documentation is built on deeplearning.net
How documentation is built on deeplearning.net
...
@@ -107,7 +98,7 @@ newly generated ones.
...
@@ -107,7 +98,7 @@ newly generated ones.
Note that the server will most definitely use a different version of sphinx
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
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
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
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).
that might increase the load of the server quite significantly).
...
@@ -147,8 +138,5 @@ TO WRITE
...
@@ -147,8 +138,5 @@ TO WRITE
*There is other stuff to document here, e.g.:*
*There is other stuff to document here, e.g.:*
* where the documentation is getting built, and epy.
* We also want examples of good documentation, to show people how to write ReST.
* 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,
