Contributing to the Documentation¶
Here we will describe the procedure through which to contribute to these Finesse documentation pages and guidelines for conventions and styles to use. The documentation is built with Sphinx and uses reStructured Text (reST) for formatting and markdown support.
Structure of the Project¶
The directory structure of the project is shown in the figure below. Each directory within
finesse/docs/source/ contains the documentation files which these pages are built from. The
sub-directories of the documentation each contain an
index.rst file which links the relevant
pages to that section of the documentation.
In order to expand a section of the documentation with another page, you must link your new reST
file in the
index.rst file of that section. Below is an example showing the index file for the
An Introduction to Finesse section of the documentation:
.. _intro: An Introduction to Finesse ========================== This section contains information regarding the key concepts of Finesse and how to use them to produce accurate frequency-domain models of any interferometer configuration you are considering. .. toctree:: :maxdepth: 1 installation key_concepts simple_example changes
The starting line (.. _intro:) defines a cross-reference label for the file so that other reST
files within the documentation can link to the introduction index page using :ref:`<intro>`.
Within the snippet above a
toctree is defined which links the listed reST files to the index
page for the introduction. As described earlier, if you wanted to link a new reST file for a
different topic within the introduction then you would simply add the name of this file to the
toctree directive list.
Writing Sphinx Compatible Docstrings¶
To produce well formatted API documentation for Finesse, all module, class and function docstrings
will be written in the numpydoc style
(follow the link for the style guide). If you installed Python through Anaconda then you should
already have the
numpydoc extension installed, otherwise run
pip install numpydoc to
In contrast to PEP-257, numpydoc asks for class
__init__ methods to be documented in the class docstring, not under the
There is currently no directly supported method for documenting properties in numpydoc, instead
you should use the Sphinx formatting syntax in the docstrings for a class property. This
involves using docstrings only for the “getter” and passing the tags :getter: and :setter:
to document both. An example is shown below for the tuning (\(\phi\)) property of the class
@property def phi(self): """The microscopic tuning of the surface. :getter: Returns the surface tuning. :setter: Sets the surface tuning. """ return self._phi @phi.setter def phi(self, value): self._phi = value
The above docstrings result in the
Surface.phi documentation page.
Showing output from inline scripts¶
Code is executed in the environment used to build the documentation, so the
finesse package is
available to import and run.
Simple code blocks can be executed with
.. jupyter-execute:: directives. More advanced usage is
possible, such as running scripts within different kernels (using the
:id: directive option),
showing line numbers, importing and showing the contents of scripts on the file system, etc. See
the jupyter-sphinx documentation for more information.
Building the Documentation¶
The documentation can be built using the Makefile provided within the
docs directory. Run
make with no arguments to print a list of available output formats. The most common output
format is HTML, which can be produced with the command
make html. Note that in order to compile
the documentation certain extra dependencies are required. These are automatically installed when
the project is installed in
dev mode, e.g. using
pip install -e .[dev].