.. _dev_document:

###############
How to document
###############

ODL is documented using Sphinx_ and a `modified version of`_ numpydoc_. An example documentation is
given below.

.. code-block:: python

   class MyClass(object):

       """Calculate important things.

       The first line summarizes the class, after that comes a blank
       line followed by a more detailed description (both optional).
       Confine the docstring to 72 characters per line. In general, try
       to follow `PEP257`_ in the docstring style.

       Docstrings can have sections with headers, signalized by a
       single-dash underline, e.g. "References". Check out
       `Numpydoc`_ for the recognized section labels.

       References
       ----------
       .. _PEP257: https://www.python.org/dev/peps/pep-0257/
       .. _Numpydoc: https://github.com/numpy/numpy/blob/master/doc/\
   HOWTO_DOCUMENT.rst.txt
       """

       def __init__(self, c, parameter=None):
           """Initializer doc goes here.

           Parameters
           ----------
           c : float
               Constant to scale by.
           parameter : float, optional
               Some extra parameter.
           """
           self.c = c
           self.parameter = parameter

       def my_method(self, x, y):
           """Calculate ``c * (x + y)``.

           The first row is a summary, after that comes
           a more detailed description.

           Parameters
           ----------
           x : float
               First summand.
           y : float
               Second summand.

           Returns
           -------
           scaled_sum : float
               Result of ``c * (x + y)``.

           Examples
           --------
           Examples should be working pieces of code and are checked with
           ``doctest`` for consistent output.

           >>> obj = MyClass(5)
           >>> obj(3, 5)
           8.0
           """
           return self.c * (x + y)

        def my_other_method(self):
            """Print the parameter.

            See Also
            --------
            my_method : some calculation, but not much
            """
            print(self.parameter)


Some short tips
---------------

* Text within backticks: ```some_target``` will create a link to the target (e.g.
  ```numpy.ndarray```).
* Make sure that the first line is short and descriptive.
* Examples are often better than long descriptions.
* Numpy and ODL are both imported by default in doctests, so there is no need for ``import numpy as np`` or ``import odl``.

Quick summary of `PEP257`_
--------------------------

* Write docstrings always with triple double quotes ``"""``, even one-liners.
* Class docstrings are separated from the class definition line by a blank line, functions and methods begin directly in the next line.
* Use imperative style ("Calculate", not "Calculates") in the summary (=first) line and end it with a full stop. Do not add a space after the opening triple quotes.
* For one-liners: put the closing quotes on the same line. Otherwise: make a new line for the closing quotes.
* Document at least all *public* methods and attributes.

Advanced
--------

This section covers advanced topics for developers that need to change internals of the documentation.

Re-generating the doc
~~~~~~~~~~~~~~~~~~~~~

The HTML documentation is generated by running ``make html`` in the ``doc/`` folder.
Autosummary currently does not support nested modules, so to handle this, we auto-generate ``.rst`` files for each module. This is done in each invocation of ``make html``.
If results are inconsistent after changing code (or switching branches), e.g. warnings about missing modules appear, run ``make clean`` an build the docs from scratch with ``make html``.

Modifications to numpydoc
~~~~~~~~~~~~~~~~~~~~~~~~~

Numpydoc has been modified in the following ways:

* The ``numpy`` sphinx domain has been removed.
* More ``extra_public_methods`` have been added.
* ``:autoclass:`` summaries now link to full name, which allows subclassing between packages.



.. _sphinx: http://sphinx-doc.org/
.. _modified version of: https://github.com/odlgroup/numpydoc
.. _numpydoc: https://github.com/numpy/numpydoc
.. _PEP257: https://www.python.org/dev/peps/pep-0257/