Contribute

Welcome to the abTEM repository! We’re excited you’re here and wish to contribute.

There are many ways you can help the community improve abTEM, with some main ones being:

• Bug reports and enhancement requests

• Add your example to the gallery

• Contribute to the documentation

• Contribute to the code base

Bug reports and enhancement requests

Bug reports are an important part of keeping abTEM a stable, robust code. Bug reports should be submitted as a GitHub issue, sharing them with the abTEM community for comments/ideas from others.

Before creating an issue, it is good practice to search existing issues and pull requests to see whether the issue has already been reported and/or fixed. Since abTEM is in active development, you should also always check whether your installed version is up to date.

Having a complete report will allow others to reproduce the bug and provide insight into fixing it. In short, a good bug report should:

1. Include a short, self-contained Python snippet reproducing the problem, see this article for tips. You can format the code nicely by using GitHub Flavored Markdown:

   ```python
   # your code goes here
   ```
   

2. Include the version of abTEM and any relevant dependencies.

3. Explain why the current behavior is wrong/not desirable, and what you expect instead.

The example gallery

Contributing an example to the gallery can be done in a few steps without any additional installations:

1. Add a notebook to the user_guide/examples/notebooks folder and a thumbnail to the user_guide/examples/thumbnails folder.

2. Update the user_guide/examples/examples.yml file with your entry.

3. Regenerate the user_guide/examples/examples.md index file using a script (to be added) and open a pull request.

Tip

Add the code for generating the thumbnail as the last cell of the example notebook. You can use the tags hide-input and remove-cell to hide the cell from the documentation rendition of the example (how to add metadata to notebooks).

Contributing to the documentation

The documentation exists in two places, under /docs in the form of markdown files and Jupyter notebooks, and as docstrings in the code library itself, which become the auto-generated API reference.

The documentation is built using jupyter-book. To generate the docs from the source, navigate to the /docs folder and run jb build . at the command line. The built site will be available in your _build\html folder.

The online documentation is automatically updated when the source is updated.

Getting started with the codebase

To get started with the abTEM codebase, take the following steps:

Clone and install

Clone the repository:

git clone https://github.com/abtem/abtem
cd abtem

Next, install:

python -m pip install -e .[testing,docs] 

This will install abTEM locally in your Python environment (we recommend using Conda), along with the packages needed to test it and the packages for producing documentation.

Optional: Install the pre-commit hooks

abTEM uses pre-commit to ensure code style before a commit is made. This ensures that the look and feel of the code remains consistent over time and across developers. We use the following tools:

• Black for standardized code formatting

• blackdoc for standardized code formatting in documentation

• Flake8 for general code quality

• isort for standardized order in imports (see also flake8-isort).

To enable pre-commit for your clone, run the following from the repository root:

pre-commit install

From now on, when you make a commit to abTEM, pre-commit will ensure that your code looks correct according to a few checks.

Run the tests

For code testing, abTEM uses pytest. The test suite also relies on hypothesis for property-based testing. You may run all the tests, or only ones that do not have a specific mark, with the following command:

pytest

You may exclude tests that require additional installations and tests that generally runs slow, for example:

pytest -m 'not requires_gpaw and not requires_gpu and not test_slow'

You can alternatively use tox to run the tests in multiple isolated environments, and also without the need for the initial dependencies install (see the tox.ini file for available test environments and further explanation):

tox -e py39-sphinx4 -- -m 'not requires_chrome and not requires_tex'