Development Guide

All contributions to svg3d 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 svg3d must adhere to the following guidelines:

  • Use a two branch model of development:

    • Most new features and bug fixes should be developed in branches based on main.

    • API incompatible changes and those that significantly change existing functionality should be based on breaking

  • Hard dependencies (those that end users must install to use svg3d) are discouraged, and should be avoided where possible.

  • All code should adhere to the source code conventions and satisfy the documentation and testing requirements discussed below.

Style Guidelines

The svg3d package adheres to a reasonably strict set of style guidelines. All code in svg3d should be formatted using ruff via pre-commit. This provides an easy workflow to enforce a number of style and syntax rules that have been configured for the project.

Tip

pre-commit has been configured to run a number of linting and formatting tools. It is recommended to set up pre-commit to run automatically:

python -m pip install pre-commit
pre-commit install # Set up git hook scripts

Alternatively, the tools can be run manually with the following command:

git add .; pre-commit run

Documentation

API documentation should be written as part of the docstrings of the package in the Google style.

Docstrings are automatically validated using pydocstyle whenever the ruff pre-commit 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 test for correct behavior. All tests should be placed in the tests folder at the root of the project. In general, most parts of svg3d 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 svg3d use the pytest testing framework. To run the tests, simply execute pytest at the root of the repository.