-
Notifications
You must be signed in to change notification settings - Fork 1
[Development] Documentation
Our documentation is built using Spinx with the numpydoc plugin and our own small plugin - sphinx-map-xrefrole. All are acquired through pip. Assuming you are inside the top level of the Menpo repository:
$ cd docs
$ pip install -r requirements.txt
To build the documentation, simply ensure you are inside the docs folder and run make:
$ make
This will then output a set of HTML documentation pages within the _build/html
directory. Make will attempt to detect when files are changed so that you can avoid doing a complete recompile when editing the RST files. However, you may need to clean the old files to make some changes go through. To do this, run make clean:
$ make clean
Numpydoc was designed by the NumPy team to be both highly legible in both the terminal and once rendered into HTML. It has the additional benefit that you can check the numpy docs for examples of good practice. For a guide of how to use this documentation class, see the numpy repo.
We use a small extension that automatically 'prettifies' our linking scheme. Any reference that was previously of the verbose form menpo.image.base.Image will be rewritten in a pretty form as Image. To use it inside the documentaton, the syntax is:
:map:`Image`
then, inside the docs
folder there is a Python file called xref_map.py
. This maps this shorthand to the proper linking scheme for Sphinx. The syntax is to add a new dictionary key mapping the shorthand name to a tuple which specifies the type of object and its absolute Package location. For example:
xref_map = {'Image': ('class', 'menpo.image.base.Image')}
The .rst
files inside docs/source
map directly to the HTML linking scheme. The index.rst
file is the classical index page for a folder structure in HTML. These index are directly converted from the ReStructured Text format into HTML by Sphinx. The top level index splits the documentation into two distinct sections:
- The User Guide
- The User Guide gives general advise on using Menpo. It contains high level explanations of core Menpo concepts and the kind of problems that Menpo is attempting to solve.
- The API
- This is 'automatically' generated from the NumpyDoc documentation. However, unfortunately Sphinx does not know how to generate documentation completely automatically. Therefore, we must create a
.rst
file for every Class and Function that we want to appear in the API documentation.
- This is 'automatically' generated from the NumpyDoc documentation. However, unfortunately Sphinx does not know how to generate documentation completely automatically. Therefore, we must create a
In general, we are attempting to expose the documentation for every TOP LEVEL Class and Function that appears in the __init__.py
at the top of a package.
Let's use the Image
package as a quick example. The documentation for the Image
package has the following folder structure:
- Image
- BooleanImage.rst
- Image.rst
- ImageBoundaryError.rst
- index.rst
- MaskedImage.rst
This folder structure says that the documentation will have an HTML link at image/
and the content at this URL will be generated from the index.rst
.
Inside the index.rst
we can write a brief description if we like, but there are a couple of important parts:
.. _api-image-index:
:mod:`menpo.image`
==================
Image Types
-----------
.. toctree::
:maxdepth: 1
Image
BooleanImage
MaskedImage
Exceptions
----------
.. toctree::
:maxdepth: 1
ImageBoundaryError
.. _api-image-index:
This represents a reference (like a label in Latex). If you want to reference this specific page anywhere in the documentation, you can using an RST reference api-image-index_
. You can see the syntax is a bit bizarre, with the underscore moving from the front to the end and the colon disappearing.
``:mod:`menpo.image``` Declares this file as a module for the top level table of contents
.. toctree::
Begins a table of contents list, which you can see in the generated output. In general this is the style we have adopted. Underneath the toctree
we list the filenames of the RST files we want to link to.
The Image
class Image.rst
file looks as follows:
.. _menpo-image-Image:
.. currentmodule:: menpo.image.base
Image
=====
.. autoclass:: Image
:members:
:inherited-members:
:show-inheritance:
Again, there are a few important elements:
.. _menpo-image-Image:
The reference again.
.. currentmodule:: menpo.image.base
The current module location that Sphinx should search when using its autoclass
functionality.
.. autoclass:: Image
:members:
:inherited-members:
:show-inheritance:
The autoclass
functionality of Sphinx which will generate documentation stubs for every public method, including inherited methods, and every property on the Class.
For completeness, an example function is as follows:
.. _menpo-landmark-imm_face:
.. currentmodule:: menpo.landmark.labels
imm_face
========
.. autofunction:: imm_face
Which we can see is identical to the class example, except we use the autofunction
functionaltiy of Sphinx instead of autoclass
.