Writing documentation¶
This documentation site uses a toolbox called Sphinx. This particular document aims to help contributors to improve the PyMedPhys documentation.
We recommend that you first read the recommended setup for contribution and file structure documentation pages before you proceed.
Prerequisites¶
You can install all of the additional dependencies required to edit the PyMedPhys documentation by running the following command in your terminal:
pip install -e .[docs]
NB: these packages are not installed if you only run
pip install -e . or conda install pymedphys.
Starting a live update documentation server¶
Within the root pymedphys directory run the following command:
sphinx-autobuild -W -p 7070 docs docs/_build/html
Then within a web browser go to http://127.0.0.1:7070
You may now edit the documentation within the docs directory and see the changes live update within your browser.
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.