Contributing#
PyEBSDIndex is a community maintained project. We welcome contributions in the form of bug reports, documentation, code, feature requests, and more. The source code is hosted on GitHub. This guide provides some tips on how to build documentation and run tests when contributing.
Building and writing documentation#
We use Sphinx for documenting functionality. Install necessary dependencies to build the documentation:
pip install --editable .[doc]
Then, build the documentation from the doc
directory:
cd doc
make html
The documentation’s HTML pages are built in the doc/build/html
directory from files
in the reStructuredText (reST) plaintext
markup language. They should be accessible in the browser by typing
file:///your/absolute/path/to/pyebsdindex/doc/build/html/index.html
in the address
bar.
Tips for writing Jupyter Notebooks that are meant to be converted to reST text files by nbsphinx:
Use
_ = ax[0].imshow(...)
to disable Matplotlib output if a Matplotlib command is the last line in a cell.Refer to our reference with this general MD
[pcopt.optimize()](../reference.rst#pyebsdindex.pcopt.optimize)
. Remember to add the parentheses()
for functions and methods.Refer to external references via standard MD like
[Signal2D](http://hyperspy.org/hyperspy-doc/current/api/hyperspy._signals.signal2d.html)
.The Sphinx gallery thumbnail used for a notebook is set by adding the
nbsphinx-thumbnail
tag to a code cell with an image output. The notebook must be added to the gallery in the index.rst to be included in the documentation pages.The PyData Sphinx theme displays the documentation in a light or dark theme, depending on the browser/OS setting. It is important to make sure the documentation is readable with both themes. This means displaying all figures with a white background for axes labels and ticks and figure titles etc. to be readable.
Running and writing tests#
Some functionality in PyEBSDIndex is tested via the pytest
framework. The tests reside in the pyebsdindex/tests
directory. Tests are short
methods that call functions in PyEBSDIndex and compare resulting output values with
known answers. Install necessary dependencies to run the tests:
pip install --editable .[tests]
Some useful fixtures, like a
dynamically simulated Al pattern, are available in the conftest.py
file.
To run the tests:
pytest --cov --pyargs pyebsdindex
The --cov
flag makes coverage.py
print a nice report in the terminal. For an even nicer presentation, you can use
coverage.py
directly:
coverage html
Then, you can open the created htmlcov/index.html
in the browser and inspect the
coverage in more detail.
To run only a specific test function or class, .e.g the TestEBSDIndexer
class:
pytest -k TestEBSDIndexer
This is useful when you only want to run a specific test and not the full test suite, e.g. when you’re creating or updating a test. But remember to run the full test suite before pushing!
Tips for writing tests of Numba decorated functions:
A Numba decorated function
numba_func()
is only covered if it is called in the test asnumba_func.py_func()
.Always test a Numba decorated function calling
numba_func()
directly, in addition tonumba_func.py_func()
, because the machine code function might give different results on different OS with the same Python code.
Continuous integration (CI)#
We use GitHub Actions to ensure that PyEBSDIndex can be installed on macOS and Linux (Ubuntu). After a successful installation of the package, the CI server runs the tests. Add “[skip ci]” to a commit message to skip this workflow on any commit to a pull request.