How to document your code

This documentation is created with Sphinx. It has automatic API build, so write good docstrings! Documentation for the latest stable lightlab is on readthedocs (link).

Todo

link to the yet-to-exist readthedocs page

If you set up CI for your lab’s fork, you might choose to host the documentation based on your lab’s development branch. See the Travis for an example of that.

When you are developing, you can build what is in your HEAD directory with make docs. Presumably, you have SSHFS setup to your instrumentation server. On that mount, navigate to lightlab/docs/_build/html/ and open index.html. This will use your default browser.

1. Manually

You can write documentation pages manually in the docs/_static/ directory using ReSt

In this documentation at the upper right corner, there is a “View page source” link that is very useful.

Bibliographic references

Use inline references with the :cite:`auth:99` directive.

At the end of the page, put this command to display the reference:

.. bibliography:: /light-bibliography.bib

The bibtex source is located at docs/light-bibliography.bib

2. Via the docstrings

Documentation of API is autogenerated. That means whatever you put in the code docstrings will end up formatted nicely on this site. It also means you have to follow some rules about it.

You should do functions like this:

def foo(a, b, *args):
    ''' My cool function
        << Blank line causes a rendered line break >>
        This function does some stuff with ``a`` and ``b``:
            * one thing
            * another thing
        << Blank line after indented thing, otherwise you get Warnings >>
        Pretty neat eh?
        << Blank line before argument list, otherwise you get Warnings >>
        Args:
            a (int): an input
            b (int): another input
            \*args: more inputs

        Returns:
            (int): an output
    '''

This is called Google docstring format. It will render as follows.

foo(a, b, *args)

My cool function

This function does some stuff with a and b:
  • one thing
  • another thing

Pretty neat eh?

Parameters:
  • a (int) – an input
  • b (int) – another input
  • *args – more inputs
Returns:

an output

Note, if you look at the source of this .rst file, the rendered documentation is in python format using lists of :param:. You should use python docstring format if manually documenting in the doc source. In the code, use Google format.

Real examples can be found by browsing the API section of this documentation. If you see something you like, click on the link to view the source. Then you can see how the docstring did that.

3. Via IPython Notebooks

The nbsphinx package by Matthias Geier can convert .ipynb files with outputs into html. The idea here is that it is sometimes instructive for the reader to play with some knobs to see how something works. Real code examples are also useful. It also supports running on build, but that is not recommended. These notebooks should be saved with outputs.

As of now, documentation notebooks are in lightlab/docs/ipynbs/. “Tests/” notebooks should correspond exactly to what is in lightlab/notebooks/Tests, and basic “Hardware/” notebooks should correspond to lightlab/notebooks/BasicHardwareBehavior. After running and saving, copy that notebook over (do not try to symlink). Other notebooks can be placed in Others/. You can reference them in the documentation like so

An example

All "Tests" notebooks

All "Hardware" IPython notebooks

All "Others" IPython notebooks