Development Guide¶
All contributions to parsnip are welcome! Developers are invited to contribute to the framework by pull request to the package repository on GitHub, and all users are welcome to provide contributions in the form of user feedback and bug reports. We recommend discussing new features in form of a proposal on the issue tracker for the appropriate project prior to development.
General Guidelines¶
All code contributed to parsnip must adhere to the following guidelines:
Hard dependencies (those that end users must install to use parsnip) are strongly discouraged, and should be avoided where possible. Additional dependencies required by developers (those used to run tests or build docs) are allowed if necessary.
All code should adhere to the source code conventions and satisfy the documentation and testing requirements discussed below.
As portability is a primary feature of parsnip, tests are run run on Python versions 3.9 and later. However, first class support should only be expected for versions covered by NEP 29.
Please refer to the Contributor Agreement for further information.
Style Guidelines¶
The parsnip package adheres to a reasonably strict set of style guidelines. All code in parsnip should be formatted using ruff via prek. This provides an easy workflow to enforce a number of style and syntax rules that have been configured for the project.
Documentation¶
API documentation should be written as part of the docstrings of the package in the Numpy style.
Docstrings are automatically validated using pydocstyle whenever the ruff prek hooks are run. The official documentation is generated from the docstrings using Sphinx.
In addition to API documentation, inline comments are strongly encouraged. Code should be written as transparently as possible, so the primary goal of documentation should be explaining the algorithms or mathematical concepts underlying the code.
Building Documentation¶
cd doc
make clean
make html
open build/html/index.html
Unit Tests¶
All code should include a set of tests which validate correct behavior.
All tests should be placed in the tests folder at the root of the project.
In general, most parts of parsnip primarily require unit tests, but where appropriate integration tests are also welcome. Core functions should be tested against the sample CIF files included in tests/sample_data.
Tests in parsnip use the pytest testing framework.
Doctests are automatically integrated with pytest via
pytest-doctestplus.
To run the tests, simply execute pytest at the root of the repository.