Documentation Guide#

This documentation site uses a toolbox called Sphinx. This particular document aims to help contributors to improve the PyMedPhys documentation.

Documentation structure and philosophy#

The PyMedPhys documentation adheres to the “Grand Unified Theory of Documentation” by Daniele Procida.

Building the documentation on your workstation#

Assuming you have set up your machine according to the appropriate development guide (Windows Setup, Linux Setup, MacOS Setup) you can then run the following within a terminal to build the documentation:

poetry run pymedphys dev docs

Docstring extraction#

Some documentation is best written right within a given function itself. This type of documentation is called a docstring. However, this documentation should also be available in the main documentation and it is exceptionally important that this isn’t written more than once. Duplicating documentation increases software entropy. As time goes by, documentation updates may result in one or more copies being missed and becoming obsolete or inconsistent with the up-to-date copy. Even if all copies are updated correctly, unnecessary duplication adds to ongoing maintenance requirements. See the DRY programming philosophy for more on this.

To solve this problem, most of PyMedPhys’ documentation is written as docstrings, which are then automatically extracted into the main documentation pages. For this to work properly, docstrings need to be formatted according to the numpy style. See the following sites for examples of how to conform to that style:

See existing examples within PyMedPhys for how to include new function docstrings into the main PyMedPhys documentation.