Contributing a recipe

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. To ensure that your contributions fit within the scope and the general style of the cookbook, please read the guidelines below.

Requirements for new contributions

All code included in this repository is executed in each pull request. This ensures that the code in this repository stays executable for a longer time frame. Because of that we do not want to have examples with heavy calculations that require more than a couple of minutes to execute. If you are unsure whether a contribution is suitable, or if you want to discuss how to structure your recipe, feel free to open an issue on the github repository.

Adding a new recipe

The examples in this repository are python files that we render for the website using sphinx-gallery. In short, these are python files containing comments formatted as RestructuredText, which are executed, and then the comments, code and outputs (including plots, print outputs, etc.) are assembled in a single HTML webpage.

To add a new example, you’ll need to create a new folder in example (substitute <example-name> with the folder name in the instructions below), and add the following files inside:

  • README.rst, can be empty or can contain a short description of the example;

  • environment.yml, a conda environment file containing the list of dependencies needed by your example;

  • as many Python files as you want, each one will be converted to a separate HTML page.

Keep in mind that sphinx-gallery will make it easy to download a Python file and the notebook generated from it, but it won’t give direct access to additional files. If your example needs such data files, there are a few options available:

  • (preferred) have the data file stored in a publicly accessible location, e.g. a Zotero record, and download the data file from the script

  • if the data files are small (few 10s of Kb) you may also include them in a data/ folder within the example folder. A zip file will be generated that can be downloaded from the example page.

Running your example and visualizing the HTML

We use nox as a task runner to run all examples and assemble the final documentation. You can install it with pip install nox.

To run your example and make sure it conforms to the expected code formatting, you can use the following commands:

# execute the example and render it to HTML
nox -e <example-name>

# build web pages for the examples that have been already run
nox -e build_docs

To visualize the generated cookbook open docs/build/html/index.html in a web browser. If there are dynamical elements that have to be loaded, it might be better to serve the website using a HTTP server, e.g. running

python -m http.server PORT_NUMBER

from within the docs/build/html/ folder. The website will be served on localhost:PORT_NUMBER.

Before committing your recipe, you should check that it complies with the coding style, which you can check automatically using

nox -e lint

Most (but not all) formatting errors can be fixed automatically with:

nox -e format

You can also build all examples (warning, this will take quite some time) with:

nox -e docs

Chemiscope widgets

If you want to visualize one or more structures, or an interactive plot, in your example, you can use a chemiscope widget. To get some ideas on how the widgets can be used to better explain the recipes, you can start looking at the examples from the cookbook.