Working with documentation#
This documentation is automatically built and published from the contents of the mxcubecore repository.
Each time the repository’s develop branch is updated, documentation is regenerated and published to https://mxcubecore.readthedocs.io/
If you want to modify this documentation, make a pull request to the repository with your suggested changes.
Modifying the documentation#
This documentation is built using the Sphinx documentation generator.
The documentation’s source and configuration files are located in the docs folder of the mxcubecore repository.
Sphinx will also read Python docstrings from the repository’s source code.
Refer to the contributing guidelines.
Building documentation#
Follow the instructions for Installing a development environment. The development environment will include Sphinx and all necessary packages for building documentation.
Attention
The installation instructions linked above are written for MXCuBE-Web, but should mostly apply equally well for MXCuBE-Core.
Once you have a working environment, use these commands to build the documentation:
# goto docs folder
$ cd docs
# build documents with Sphinx
$ make html
The commands above will generate documentation in docs/html/ directory.
The generated docs can be viewed by opening docs/html/index.html in your web browser.
More details about documentation system#
The documentation system is built around Sphinx.
There is a Makefile in the docs directory,
that allows building the documentation with a simple command like the following:
make html
But the actual build is performed by the sphinx-build program.
From the root of the project,
a command like the following should build the HTML documentation:
sphinx-build -M html docs/source docs/build -c docs
The theme used is furo.
Markup#
The default markup language for Sphinx is reStructuredText. The usage of Markdown to write documents is enabled via MyST. Note that for special Sphinx features such as roles, directives, and so on, the Sphinx documentation focuses on the Restructuredtext notation only. To learn how to use these features in Markdown documents, one should refer to the MyST documentation. The docstrings in Python code are still to be written with Restructuredtext syntax, though.
Python code#
The documentation system is configured to generate API documentation
based on the Python code.
The Sphinx extension used to do this is
autosummary.
This extension imports (or even runs?) the code in order to do its work.
The
napoleon
extension is enabled to handle docstrings within the Python code
and it is configured for
Google-style docstrings.
Diagrams#
The
sphinxcontrib-mermaid
extension is enabled to allow embedding Mermaid diagrams
in the documentation.
For example the following code in a Markdown document:
```{mermaid}
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
```
or the following in a ReStructuredText document:
.. mermaid::
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
produce the following diagram: