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:
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 ```
Include the version of abTEM and any relevant dependencies.
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:
Add a notebook to the
user_guide/examples/notebooks
folder and a thumbnail to theuser_guide/examples/thumbnails
folder.Update the
user_guide/examples/examples.yml
file with your entry.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'