Building documentation

If you’ve made significant changes to the documentation, you can build a local to see how your changes are rendered. You will need to install Sphinx, the Napoleon extension (to enable NumPy docstring support), and the Read the Docs theme. You can do this by installing the optional docs requirements.

For Blocks:

$ pip install --upgrade git+git://github.com/user/blocks.git#egg=blocks[docs]

For Fuel:

$ pip install --upgrade git+git://github.com/user/fuel.git#egg=fuel[docs]

After the requirements have been installed, you can build a copy of the documentation by running the following command from the root blocks (or fuel) directory.

$ sphinx-build -b html docs docs/_build/html

Docstrings

Blocks and Fuel follow the NumPy docstring standards. For a quick introduction, have a look at the NumPy or Napoleon examples of compliant docstrings. A few common mistakes to avoid:

  • There is no line break after the opening quotes (""").
  • There is an empty line before the closing quotes (""").
  • The summary should not be more than one line.

The docstrings are formatted using reStructuredText, and can make use of all the formatting capabilities this provides. They are rendered into HTML documentation using the Read the Docs service. After code has been merged, please ensure that documentation was built successfully and that your docstrings rendered as you intended by looking at the online documentation (for Blocks or Fuel, which is automatically updated.

Writing doctests is encouraged, and they are run as part of the test suite. They should use Python 3 syntax.

References and Intersphinx

Sphinx allows you to reference other objects in the framework. This automatically creates links to the API documentation of that object (if it exists).

This is a link to :class:`SomeClass` in the same file. If you want to
reference an object in another file, you can use a leading dot to tell
Sphinx to look in all files e.g. :meth:`.SomeClass.a_method`.

Intersphinx is an extension that is enabled which allows to you to reference the documentation of other projects such as Theano, NumPy and Scipy.

The input to a method can be of the type :class:`~numpy.ndarray`. Note that
in this case we need to give the full path. The tilde (~) tells Sphinx not
to render the full path (numpy.ndarray), but only the object itself
(ndarray).

Warning

Because of a bug in Napoleon you can’t use the reference to a type in the “Returns” section of your docstring without giving it a name. This doesn’t render correctly:

Returns
-------
:class:`Brick`
    The returned Brick.

But this does:

Returns
-------
retured_brick : :class:`Brick`
    The returned Brick.