Markov Chain Monte Carlo for fun and profit

🎲 ⛓️ 👉 🧪

Adding Documentation

References:

• Intro to basic ReStrutured Text

• Getting started with Sphinx

If we produce software that might be used by others even colleagues, it’s imperative to document how it works and should be used.

The classic way to do this in the python community is to use a tool called Sphinx, you’ll probably be quite familiar with pages generated by Sphinx if you’ve ever used any python packages. To give you teaser by the end of this chapter we will have an autogenerated website for the project that looks like this

We’ll use sphinx along with a couple plugins: autodoc allows us to generate documentation automatically from the docstrings in our source code, while napoleon allows us to use NUMPYDOC and Google formats for the docstrings in addition to reStructuredText

What this means is that we’ll be able to write documentation directly into the source code and it will get rendered into a nice website. This helps keep the documentation up to date because it’s right there next to the code and the web-based documentation will get automatically re-generated every time the documentation files are updated!

This means that the part of our source code that looks like:

will get rendered to this:

Installation

Make sure sphinx is installed in the environment then make a folder called docs/, cd into it and run sphinx

% mkdir docs
% cd docs
% sphinx-quickstart #just go with the defaults

This will populate docs with a skeleton sphinx project, to tell sphinx where to find our code we’ll add some lines to conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('../src'))
#since conf.py is in docs/ the path ../src points to where our module is

We add the extensions by adding this to conf.py too:

extensions = [
    'sphinx.ext.autodoc',   # for generating documentation from the docstrings in our code
    'sphinx.ext.napoleon',  # for parsing Numpy and Google stye docstrings
    'sphinx.ext.mathjax',   # for equation rendering

]

Writing docstrings

Numpy style docstrings look like this:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

I normally just copy and paste this and go from there, but there’s a full description here. You can also check out the docstrings in MCFF.

Making the function declarations a bit nicer

Longer function names in the generated documentation currently generate with no line break, I found a fix for that buried inside a bug report on sphinx

It involves adding some custom CSS and an extra line to conf.py:

html_css_files = [
    'custom.css',
]

Finally, we add a readthedocs.yaml file (which you can copy from the root of this repo) to tell readthedocs how to build our documentation. https://docs.readthedocs.io/en/stable/config-file/v2.html#packages

And the documentation is now hosted online!

Documentation Ideas

Readthedocs can be a bit tricky to set up, it is also possible to use GitHub Pages to accomplish something similar. Another idea is to include some simple copyable code snippets in a quickstart guide. This lets people get up and running with your code more quickly than if they need to read the API documentation to understand how to interact with your module.

%load_ext watermark
%watermark -n -u -v -iv -w -g -r -b -a "Thomas Hodson" -gu "T_Hodson"

Author: Thomas Hodson

Github username: T_Hodson

Last updated: Mon Jul 18 2022

Python implementation: CPython
Python version       : 3.9.12
IPython version      : 8.4.0

Git hash: 03657e08835fdf23a808f59baa6c6a9ad684ee55

Git repo: https://github.com/ImperialCollegeLondon/ReCoDE_MCMCFF.git

Git branch: main

Watermark: 2.3.1