.. _metadocumentation:

==================================================
Documentation Documentation AKA Meta-Documentation
==================================================


How to build documentation
--------------------------

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.

.. code-block:: bash

    cd Theano/
    python ./doc/scripts/docgen.py

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

.. code-block:: bash

    cd Theano/
    python ./doc/scripts/docgen.py --nopdf


For more details:

.. code-block:: bash

   $ 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 <http://docutils.sourceforge.net/rst.html>`__ 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.

    .. TODO: Check it out, this won't appear.
    .. Nor will this.


How documentation is built on deeplearning.net
----------------------------------------------

The server that hosts the theano documentation runs a cron job roughly every
2 hours that fetches a fresh Theano install (clone, not just pull) and
executes the docgen.py script. It then over-writes the previous docs with the
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@.

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

pylint
---------------------------------------

pylint output is not autogenerated anymore.

Pylint documentation is generated using pylintrc file: ``Theano/doc/pylintrc``


.. _metadocumentation_nightly_build:

The nightly build/tests process
---------------------------------------

We use the Jenkins software to run daily buildbots for Theano, libgpuarray and
the Deep Learning Tutorials. Jenkins downloads/updates the repos and then runs their test
scripts. Those scripts test the projects under various condition.
Jenkins also run some tests in 32 bit Python 2.7 and Python 3.4 for Theano.

The output is emailed automatically to the `theano-buildbot`_ mailing list. The
jenkins log and test reports are published online:

* `Theano buildbot <http://darjeeling.iro.umontreal.ca:8080/job/Theano_buildbot_multijob/>`__
* `gpuarray buildbot <http://darjeeling.iro.umontreal.ca:8080/job/Buildbot_gpuarray/>`__


.. _theano-buildbot: https://groups.google.com/group/theano-buildbot

TO WRITE
---------------------------------------

*There is other stuff to document here, e.g.:*

 * We also want examples of good documentation, to show people how to write ReST.

