About this documentation#
We document for both users and developers:
The api docs is for users quickly wanting to read the documentation of a specific method.
Users new to this package should look at the examples.
The developer documentation is for developers that want to understand this package or know more about how we develop.
The functional descriptions aim to describe what this package is designed to do, independent of programming language. These documents act as the blue print when developing features. The standards and norms described in the developer documentation and the functional descriptions should be enough to implement a feature.
The documentation required for new features#
The first documentation that should exist is a functional description. Ideally, this should be written before any code, as that ensures that the code is tailored to the requirements and not the other way around. Docstrings are required for all public classes, methods and functions. For internal-only components, docstrings are optional. Extra user guides and examples are not always needed, but should be provided if the user has to do “new” things to use this feature.
About writing documentation#
We aim to write documentation in a way that is easy to produce and can be automatically converted into a more readable format. For now, we use markdown to write most documentation. Only the docstrings in the code are in reStructuredText. The flavour of markdown that we use is MyST, which stands for Markedly StructuredText. MyST is a strict superset of CommonMark.
MyST has been configured with dollarmath and amsmath enabled. The dollarmath extension allows inline LaTeX expressions using dollar-sign syntax, like this: $a^2 = b^2 + c^2$ to write \(a^2 = b^2 + c^2\). The amsmath extension enables full LaTeX math environments to be used directly in MyST markdown, for example:
\begin{gather*}
a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
\end{gather*}
This renders as
Another enabled extension is Mermaid, which allows you to write diagrams like this:
```{mermaid}
graph TD
A[Start]-->B[End]
```
graph TD
A[Start]-->B[End]
Using jupyter notebooks as documentation is not supported. They introduce significant additional dependencies, and make pull requests more difficult to review.
Since notebooks can be exported to markdown, there is little added value to rendering notebooks by the documentation build system.
Notebooks can be rendered by the developer and exported to markdown by running
jupyter nbconvert --to markdown xx.ipynb, where xx is the name of your notebook.
About building and publishing documentation#
The languages to write documentation are MyST and reStructuredText, but the language to view the documentation online is HTML (and others). The main tool to do the translation is sphinx. We use sphinx with the following extensions:
autodoc to include the docstrings in the online documentation.
myst_parser to enable markdown.
mermaid to render diagrams.
The documentation is hosted on ReadTheDocs.io, which is a platform specifically for hosting documentation of code.
Readthedocs.io is configured (via a github app) to build the documentation of the develop branch and of pull requests. It automatically builds the documentation when there is a new push to develop or a (commit to) a pull request. To build the documentation, readthedocs.io first clones the repository. The file .readthedocs.yaml specifies how readthedocs.io should build the documentation.
The first step to building the documentation is installing this package (synthpop) including the docs dependency group (poetry install --with docs). See the readme on how to install Poetry. The package needs to be installed so that autodoc can import every module to access the docstrings. Sphinx then parses everything to HTML. The HTML can then be served on synthpop-py.readthedocs.io