Documentation

The documents are written in RST and generated with Sphinx, the build is performed via the Sphinx integration with setuptools.

The most recent release of Sphinx can be installed from PyPI via pip install sphinx (the version available via the Ubuntu repositories does not include all extensions that are required to build the documentation).

The documentation is version controlled along with the code, therefore it is beneficial to make relevant changes to the documentation as the code is modified.

Workflow

TL;DR of building the documentation.

Run the commands:

python setup.py docs

This will create the documentation in the docs/build/html directory.

If you also want to publish the docs (note this is normally done as an automated process):

python setup.py docs_publish

API Documentation

The API documentation must be generated prior to building the documentation. This is done with the command: python setup.py docs_api.

HTML

The HTML pages can be built using python setup.py docs, which will build the documentation in docs/build.html.

There is a setuptools command configured to deploy the documentation to GitHub Pages where it will be visible at https://mantidproject.github.io/mantidimaging

This can be done via the command python setup.py docs_publish. This assumes you are using SSH as your Git push protocol, if you are not you may specify an alternative remote URL using the -r argument.

QtHelp

It is also possible to use Sphinx to build the documentation as a Qt Help project.

This can be done with the command: python setup.py docs -b qthelp.

Release Notes

Release notes should be continuously updated during developement. Almost all pull requests should have an update to the relevant file and section in docs/release_notes

For the current development work, new release notes go in an individual file for each pull request. This prevents merge conflicts that would occur if two PRs directly edited the same release note file. For example the PR fixing issue #1792 by updating Python would have its change note placed in docs/release_notes/next/dev-1792-python-310. The content would be a line:

#1792 : Update python to 3.10

These will be included into the relent section in docs/release_notes/next.rst. At release time the notes can be collected up using:

python setup.py release_notes

and added to the release notes. The individual files can then be deleted.

When fixes are backported to a release branch, they can be added to the notes for that release, in an updates section.

Logging

Logging can be controlled using the QSettings configuration file .config/mantidproject/Mantid Imaging.conf on Linux or the equivalent registry keys on windows (See QSettings). For example:

[logging]
log_level=DEBUG
log_dir=/tmp/mantid_imaging_logs
performance_log=true

Benchmarking and profiling

Mantid imaging has some utilities to help with benchmarking and profiling.

The context managers ExecutionTimer and ExecutionProfiler can be used to wrap some lines of code to record and log its run time. For example:

with ExecutionProfiler(msg="a_slow_function()"):
    a_slow_function()

will record and log a profile of function calls and times within a_slow_function().