Writing documentation

Documentation comes in two parts: docstrings and user-guide documentation.

Docstrings

Written at the start of a function, they give essential information about how it should be used, such as which arguments can be passed to it and what the syntax should be. The docstrings need to follow the numpy specification, as shown in this example.

As a general rule, any code that is part of the public API (i.e. any function or class that an end-user might access) should have a clear and comprehensive docstring explaining how to use it. Private methods that are never intended to be exposed to the end-user (usually a function or class starting with an underscore) should still be documented to the extent that future developers can understand what the function does.

You can check your docstrings follow the convention by using the flake8-docstrings extension, like this:

# If not already installed, you need flake8 and flake8-docstrings
pip install flake8 flake8-docstrings

# Run flake8 on your file
flake8 /path/to/your/file.py

# Example output
/path/to/your/file.py:46:1: D103 Missing docstring in public function
/path/to/your/file.py:59:1: D205 1 blank line required between summary line and description

User-guide documentation

A description of the functionality of the code and how to use it with examples and links to the relevant code.

When writing both the docstrings and user guide documentation, it is useful to have some data which the users can use themselves. Artificial datasets for this purpose can be found in hyperspy.datasets.artificial_data.

Build the documentation

To check the output of what you wrote, you can build the documentation by running the make command in the hyperspy/doc directory. For example make html will build the whole documentation in html format. See the make command documentation for more details.

To install the documentation dependencies, run either

$ conda install hyperspy-dev

or

$ pip install hyperspy[build-doc]

When writing documentation, the Python package sphobjinv can be useful for writing cross-references. For example, to find how to write a cross-reference to hyperspy.signal.BaseSignal.set_signal_type(), use:

$ sphobjinv suggest doc/_build/html/objects.inv set_signal_type -st 90


Name                                                      Score
---------------------------------------------------------  -------
:py:meth:`hyperspy.signal.BaseSignal.set_signal_type`      90