How to add an example

How to add an example#

Contributions to ASE are very welcome and appreciated.

GitLab repository#

Our examples are all part of the main ASE Gitlab repository.

Please read and follow our contribution guidelines (How to contribute).

You can find the source code of existing examples in the examples folder in Gitlab. These are rendered to pages in the Examples on the ASE website.

Tutorial Guidelines#

When contributing a new example, it should roughly have the following structure:

  • Learning outcomes and Objectives: describe the task and the aim of the tutorial

  • Imports

  • Setup: load necessary data

  • Task description: describe the basic functionality of used functions and add links to the ASE documentation where needed

  • Basic working example

  • Further information: links, literature, references to the documentation

Adding an Example#

You need to following to add an example:

  • a clone of your fork of the ase gitlab

  • a python environment with relevant packages installed. These are defined in the ase “docs” dependency group and can be installed with

$ pip install ase[docs]

Location of Examples#

All examples are located in the examples folder. More advanced ASE tutorials can be found in the folder examples/tutorials, which is most likely where you want to add your contribution. There is also an examples/python folder for python related tutorials.

Format of Examples#

In the folder, all examples are collected as .py files. These .py files must contain a title in reStructuredText.

Note

Please do not use any non-human written files such as .png files in the tutorials, generate them during the tutorial if possible. Also, do not add large files (> few 10s of Kb). Sphinx-gallery creates a downloadable .zip folder for all examples, so we want to keep it light.

Adding a .py file to the example folder will automatically make sphinx-gallery find it and it will be executed when building the gallery.

Linting#

We use a linter that checks all the examples commited. Please check your example before commiting and apply the changes necessary so it passes a linter without complains. Your merge request will not be accepted unless all tests passed, which also includes linting. The linter we are using for our CI check is Ruff.

You can simply install it with pip:

$ pip install ruff

Before opening a merge request for your example, please make sure that these two checks are passed when executed in the ase folder:

$ ruff check

$ ruff format
Contents