Documentation

The ESPResSo documentation is generated during nightly builds and deployed to https://espressomd.github.io. The following sections will guide you through the different types of documentation available in ESPResSo and how to edit them.

Table of Contents Tutorials Checklist Sphinx Doxygen Developer wiki GitHub Pages

Tutorials

The tutorials showcase ESPResSo's features and explore a variety of scientific topics using interactive browser-based simulations. We use Jupyter notebooks to create interactive sessions. Some solutions are hidden using the exercise2 plugin. Please install all dependencies with the following commands:

pip3 install --user jupyter_contrib_nbextensions
jupyter contrib nbextension install --user
jupyter nbextension enable rubberband/main
jupyter nbextension enable exercise2/main

To create a hidden solution, select a code cell, convert it to markdown and fence the code with ```python before the first line and ``` after the last line to pygmentize the code. Then use Shift+left-click to drag a red box around the markdown cell containing the question and the markdown cell containing the code solution to highlight them both (only works if you have the rubberband extension active, otherwise use keyboard shortcuts), then click on the exercise2 button to hide the solution. You can have multiple solutions to the same question if you select more that two cells. You may insert an empty code cell below the hidden solution. In CI, empty cells below solutions are deleted. Hidden solutions are made visible, and if a solution markdown cell contains only code, it will be converted to a code cell and executed.

To make plots more readable, configure matplotlib in the first cell with:

import matplotlib.pyplot as plt
plt.rcParams.update({'font.size': 18})

You typically want to draw plots with a figure object of size 10x6, so as to maximize the width of the plotting area. You also want to add plt.show() at the end to prevent Jupyter from printing a string representation of the last matplolib object. This also prevents Jupyter from accidentally stacking together plots from different cells.

fig = plt.figure(figsize=(10, 6))
plt.plot(obs[0, :], label='v = 1.0')
plt.plot(obs[2, :], label='v = 5.0')
plt.xlabel('$i$')
plt.ylabel('$X_i$')
plt.legend()
plt.show()

When opening a PR to create a new Jupyter notebook, please make sure to clear the output of the notebook before committing your changes. To this effect, click on the drop-down menu "Cell", go to "All Output" and click "Clear". This will reset all code cell labels to "In [ ]:" and remove any standard output, plot images or video that may have been generated when running the code, which would otherwise make the diff unreadable. After the PR is merged, the tutorial is automatically run and deployed to https://espressomd.github.io/tutorials.html within one day.

When creating a new tutorial, please write adequate integration tests using the explanations in Testing Tutorials. You will not only need to check the numerical results, but also tweak simulation variables to make the tutorial run within a minute or so. Once ready with these tests, you can re-use the same variable substitution logic to configure the CMakeLists.txt of the new tutorial. For example in the electrokinetics tutorial, you will find the following lines:

nb_export(TARGET tutorial_ek SUFFIX "" FILE "electrokinetics.ipynb"
          HTML_RUN
          VAR_SUBST "integration_length=600;dt=0.5"
          ADD_SCRIPTS "scripts/eof_analytical.py;scripts/plot.py")

The optional argument HTML_RUN will run the Jupyter notebook before converting it to HTML, VAR_SUBST will perform variable substitutions like in the tutorial tests (here, provide a semicolon-separated list of key/value pairs) and ADD_SCRIPTS will include bonus scripts in new code cells at the end of the notebook. Please note the variable substitutions don't have to be exactly the same as in the tutorial tests: when exporting a notebook to HTML, the simulation should be long enough to produce clean plots. Most tutorials take 2-3 min of running time during the export stage.

Once ready with the new tutorial, edit doc/tutorials/CMakeLists.txt to include the tutorial subdirectory, then write a short description of the tutorial in doc/tutorials/Readme.md, which is used to generate the HTML landing page, and write the same short description in doc/sphinx/introduction.rst, which is used to generate the user guide. For an example, you can look at 4856dba which shows the complete creation of the error analysis tutorial in ESPResSo 4.2. Finally, write tutor notes in a file NotesForTutor.md, which is used during the summer school to help new tutors get started with the tutorial. The file should document the learning objectives and highlight areas of difficulty for students with no prior experience with ESPResSo (e.g. MD reduced units, correlator framework, statistical tools and how to draw independent samples, etc.).

Checklist

Files to create:

• doc/tutorials/mytutorial/mytutorial.ipynb
• doc/tutorials/mytutorial/CMakeLists.txt
• doc/tutorials/mytutorial/NotesForTutor.md
• testsuite/scripts/tutorials/test_mytutorial.py

Files to update:

• doc/tutorials/CMakeLists.txt
• doc/tutorials/Readme.md
• doc/sphinx/introduction.rst
• testsuite/scripts/tutorials/CMakeLists.txt

Sphinx

This is the user guide documentation. It describes all ESPResSo features and contains the installation instructions. Sphinx reads the .rst files in doc/sphinx/ and extracts the docstrings from the Python and Cython files in src/python/. We use the NumPy documentation style for docstrings with sphinx.ext.napoleon, and the reStructuredText syntax in .rst files, for which you can find an excellent introduction in the reStructuredText Primer and the full specifications for a more advanced usage.

After merging a pull request into the master branch, the Sphinx documentation is automatically compiled and deployed to https://espressomd.github.io/doc/index.html.

Malformed Sphinx documentation will not pass CI! In the build directory, execute make -t; make sphinx; ../maintainer/CI/doc_warnings.sh using the maxset configuration to run Sphinx and the syntax checker. The syntax checker will list all links introduced by roles (e.g. :func:`integrate`) to non-existent functions/methods/classes/attributes. These links must be updated whenever the referenced object changed name or namespace, otherwise CI will fail. The syntax checker will also highlight possible typos in roles (e.g. :obj:float`, which is missing a backtick and will appear as-is in the HTML output), but these won't fail CI.

Doxygen

This documentation is mostly relevant to developers. Implementation details of core functions are written in the source code using Doxygen comments (.hpp/.cpp files for C++ code, .cuh/.cu files for CUDA code). Algorithms and Python interfaces are detailed in stand-alone Related Pages (.dox files). We use the standard Doxygen syntax, for which you can find the full specifications in the manual, together with LaTeX formula, Markdown syntax for Related Pages and sometimes HTML commands when there is no equivalent Doxygen markup command. We use both the @param and \param syntax, with a preference for the former.

After merging a pull request into the master branch, the Doxygen documentation is automatically compiled and deployed to https://espressomd.github.io/dox/index.html.

Malformed Doxygen documentation will not pass CI! We try to keep Doxygen warnings to a minimum. In the build directory, execute make doxygen; ../maintainer/CI/dox_warnings.sh using the maxset configuration to run Doxygen and the syntax checker. The syntax checker will list all warnings that require fixing. Warnings caused by known Doxygen bugs or that don't change the HTML output are ignored. Please refer to #2605 for the list of warnings that can be safely ignored and for Clang compiler options used to detect common errors left unreported by Doxygen. In particular, do not write function parameter or template parameter without a description (e.g. @param arg1 followed by a newline) to silence a warning about missing parameter documentation, as the @param command will in this situation take whatever text is on the following lines as the arg1 description until it reaches a paragraph-level markup command (e.g. another @param).

The documentation of each function should contain a @brief description, if necessary a more detailed description and a description for the return value (@return, @retval) and parameters (@param, @tparam). This documentation should preferably be located above the function prototype if there is one, otherwise above the function definition. We configured the Doxyfile to merge the documentation of a function definition into the documentation of its prototype.

Look at the documentation of existing files and functions to get a feeling how it should be!

Doxygen is able to understand simple LaTeX and HTML commands as well as some special command in order to give the documentation a nice structure and to make it more readable. In the following list you find a short description of the most common commands we need:

• @param [ direction ] name description

  Document the parameter of a function. Use the optional direction specifier when an argument is an output argument. Never leave the description field empty!

• @return description

  Document the return value of a function.

• @retval value

  Document a return value (numerical constant, enum value, error code...). Stack multiple @retval if the function can return multiple values.

• @anchor name description

  Create an anchor to which you can refer using the @ref command.

• @ref name [ "text" ]

  Insert a link to another object in the documentation, e.g. an anchor, a function, a class. Optionally, you can change the name of the referenced object, e.g. to strip a namespace. For overloaded function, provide the function full signature.

• [title](http://www.your_url.html)

  Link to an external HTML source.

• @file name description

  Special anchor for a file, typically the name is left out and the description moved to the next line.

• @image html image

  Include a picture. The picture file should reside in the subdir doc/doxygen/figs. Do not use the HTML <img>-tag to include pictures, as doxygen will not copy the pictures into the documentation.

• @li List entry 1 @li List entry 2

  Create a list in the documentation. Avoid using the HTML structure <ul> <li>List entry 1</li> <li>List entry 2</li></ul>, which is prone to errors.

You can access the full list on the Doxygen Special Commands page.

Developer wiki

The developer's guide is stored in the GitHub wiki. It contains the coding style guide, explains ESPResSo design decisions, gives instructions for new contributors, and provides a release checklist.

The wiki also provides a list of upcoming ESPResSo releases and the archives of the core developer meetings.

GitHub Pages

The https://espressomd.github.io website is managed by the espressomd/espressomd.github.io repository. The pages are written in Markdown and converted to HTML via pandoc using a Jekyll theme. There is a GitHub Action running daily to check if the python branch has changed, in which case the HTML files are regenerated. To generate the website locally, follow the instructions in the deploy_docs action.

To modify the website, open a pull request against the landing_page branch.

To add a static page:

1. create a new Markdown page (see espressomd/espressomd.github.io@b842f04)

To add a dynamic page that extracts information from the python branch or from the CI pipeline artifacts:

1. write the information to extract in the main repository with invisible delimiters (see espressomd/espresso@c4445ed)
2. create a Markdown template and a Python script to extract the information using the delimiters (see espressomd/espressomd.github.io@b373f87)
3. add a new command to call that Python script in the daily action (see espressomd/espresso@08ff6bc)