[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

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.

Class Mapping

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')}

How do the .rst files map to the built documentation?

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.

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.

Example using Image 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.

Example index

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.

Example Class

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.

Example function

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.