Contributing to the documentation

Here we describe the guidelines and conventions for contributing to the Finesse documentation.

How to build the documentation

A pdf and an html version of the documentation need to be built as part of the GitLab pipeline. They need to be manually triggered after the build jobs are completed. The generated pages can be accessed in the artefacts of the documentation building jobs. However, this is often not a convenient way to iterate when writing the documentation, and a local build of the documentation can be more efficient.

The documentation system uses Sphinx to build the document(s). If Finesse was installed for code development in the conda environment file (./environment.yml), everything needed should already be installed. If not, consult Installing Finesse for how to install Finesse.

The documentation can be built locally using the make commands executed in the docs/ subdirectory. Run make with no arguments to print a list of available output formats. For example:

make html

This will generate the website version in the docs/build/html directory (with docs/build/html/index.html as the landing page).

The build process can be quite long. To speed it up, you can skip building the API documentation pages, which takes a long time:

make html_no_api

or skip also the executing of the jupyter code using

make html_no_api_no_jupyter

To remove temporary files created during the build process, use:

make clean

Note

To build the PDF docs (using make latexpdf), you must ensure that a comprehensive LaTeX package (such as texlive) is available on the system path.

Supported formats

Finesse documentation supports two formats for creating pages:

• reStructured Text (reST)

  The primary format supported by Sphinx is reStructured Text. Each .rst file corresponds to a page in the documentation. The extension jupyter_sphinx allows executing Python code and displaying the results directly in the documentation, including in the API pages generated from the Python docstrings.

• MyST-NB

  It is possible to write jupyter notebooks (.ipynb) that can be included directly in the documentation, while still being fully compatible with jupyter. It is an easy way to create pages or code examples. MyST-NB adds some notations to the standard markdown used in the jupyter notebook to allow a seamless integration with Sphinx and reStructured Text.

  The JupyterLab plugin jupyterlab-myst can be installed using pip or the JupyterLab plugin manager and will allow the rendering of some MyST-NB specific formatting.

There is no preferred method to create a documentation page; the choice is left to the author. Newcomers may find it easier to write Jupyter notebooks as they are probably already familiar with the format, and it allows a live rendering of the page that closely resembles the final product (especially with the JupyterLab plugin).

See the Authoring documentation section for more information about the two formats.

Directory organization

docs

Root directory for the documentation. Notably, it contains the Makefile file defining the build target.

docs/source

Contains the source files for the documentation and the Sphinx config file conf.py. Each subdirectory inside docs/source corresponds to a section and contains the files needed to generate it.

Each directory, including docs/source, contains a file named index.rst. Any new page needs to be added to that index file to be shown in the table of contents of the documentation.

docs/build

This is where the documents created using make will be generated, each in their subdirectory.

docs/resources

Contains some resource files (like images). Resource files are also present in the source subdirectories.

Updating the Changelog

In principle, every change made to Finesse that is relevant to Finesse users should be documented in the Changelog. Internal changes relevant only to the developers can be left out. We follow the format from keepachangelog. Special care should be taken to document changes that are not backwards compatible (i.e. will break existing code) and changes that will quietly change the scientific output of existing code.

The changelog should always have a section on top titled ‘Next Release’, which should be replaced with the actual version when Releasing finesse. It is encouraged to write a small summary of the changes, highlighting the most important ones so users don’t have to scroll through all items to see if something is relevant. If possible, the changelog should refer to actual documentation pages, but it can include small code snippets or comparison plots highlighting the different output between the new and old versions.

Comments and todo items

The .. todo:: directive will add a highlighted todo item in the manual. These should be used only as placeholders for larger sections, such as .. todo:: This section is missing for a missing section. For internal todo items such as ‘fix this later’, a simple comment can be used, for example: .. Todo: fix this later.

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).

Note

In contrast to PEP-257, numpydoc asks for class __init__ methods to be documented in the class docstring, not under the __init__ method itself.

Note

There is currently no directly supported method for documenting properties in numpydoc, instead you should use reST 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 nr property of the class BeamParam:

@property
def nr(self):
    """The refractive index associated with the `BeamParam`.

    :`getter`: Returns the index of refraction.
    :`setter`: Sets the index of refraction.
    """
    return self.__nr

@nr.setter
def nr(self, value):
    self.__nr = value

The above docstrings result in the finesse.gaussian.BeamParam.nr documentation page.

Documenting Cython extensions

See Documenting Cython extensions.

Style guide

Finesse is developed by many people and maintaining consistency across the documentation is essential. The following subsections describe some style aspects to be conformed to when writing documentation.

Where style guidance is undefined, conform first to the rules enforced by doc8 then the Python documentation style guide.

Line length

Try to stick to a maximum of 88 characters. This is consistent with the rules for Python code, set by Black. This limit isn’t just for aesthetics in your IDE: code blocks in documentation pages with longer lines will overflow the visible page and create irritating horizontal scroll bars.

You may wish to create a ruler in your IDE to give a visual cue for this limit.

Hint

In some editors you can highlight a block of text and press Alt + Q to automatically wrap the text at the configured line length. In Visual Studio Code you might wish to install the Rewrap extension to enable this shortcut, and set a ruler in .vscode/settings.json using e.g. "editor.rulers": [88],.

Style

Try not to write documentation with many nested subsections; documentation should be mostly prose. Only the first four section levels are displayed in the sidebar of the HTML documentation, and each level beyond the top level is hidden until its parent is navigated to. If a section makes sense to appear in the sidebar then it should be within the top four levels; use common sense.

Titles

Section titles should use sentence case, e.g. Showing output from inline scripts, not Showing Output from Inline Scripts.

Do not use backtick-style (``thing``) or replacement (e.g. |Finesse|) formatting in titles as these do not render nicely in the sidebar. Instead you could consider using single quotes, e.g. “Logging via the Python ‘logging’ module”.

Code examples

Code examples should follow the same style <code_style> as Finesse itself.

Grammar

Tone

Use an affirmative, succinct tone. Concise is better than verbose. Users typically don’t read whole pages of documentation but rather arrive at particular sections via links or search results.

English

Use of US English is preferred, for consistency with the Python documentation; however, refactoring existing text just for the sake of changing English forms is discouraged - focus your efforts on something more fruitful. As with the Python documentation, consistency within a page or section is more important than global consistency.

References to Finesse

Finesse 3 should be referred to in the documentation simply as Finesse. Explicit inclusion of version numbers should only be made when referring to or comparing differences in behaviour.

Core documentation should focus on explaining how Finesse 3 works, not how it’s different to other tools or previous versions. Discussions of differences between Finesse 2 and 3 should be kept in relevant sections. It’s fine however to include brief “see also” directives in Finesse 3 documentation pointing to such discussions.

Capitalisation

Various Finesse-related terms have particular capitalisation conventions. Some are also defined as macros which format the text appropriately:

• |Finesse|, not e.g. FINESSE

• Pykat, not e.g. PyKat

• KatScript, not e.g. kat script, katscript, or kat-script

Linting tools

The doc8 package provides a command line tool to check documentation. Running doc8 from the project root directory will have it automatically pick up the line length setting defined in pyproject.toml. For instance, you can lint the whole documentation source with:

$ cd /path/to/finesse/git/project/  # The directory that contains pyproject.toml.
$ doc8 docs/source

This will print a list of files and their corresponding issues, if any.