Skip to main content
`Ctrl`+`K`

# 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 as the Tutorials on the ASE website.

## Sphinx-Gallery

We are using Sphinx-Gallery to test and display our examples. Every time a change is proposed on Gitlab (to the code or the documentation), all examples are tested and errors are flagged.

## 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

### Building the Gallery

You can build the gallery from the ‘doc’ directory. For this, you can run the following two commands from the terminal:

    $ make html

    $ make browse