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
$ pip install --upgrade git+git://github.com/user/blocks.git#egg=blocks[docs]
$ 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
$ sphinx-build -b html docs docs/_build/html
- 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).
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.