Skip to content

Development

Contributions are welcome. This page covers testing, code style, building the docs, and the release process. Most tasks are also wrapped as make targets — run make help for the full list.

Setup

Install with the dev and test tooling:

uv pip install -e ".[all,dev,test]"
# or: make install-dev

Tests

pytest                       # all tests
pytest -m "not slow"         # skip slow tests
pytest --cov=alinemol --cov-report=term-missing   # with coverage

# Or via the test runner (supports categories)
python run_tests.py all      # unit | integration | fast | coverage

DGL / GraphBolt

Set DGL_SKIP_GRAPHBOLT=1 when running tests (CI does this automatically) to avoid GraphBolt import errors with the pinned torch/DGL versions.

Code style

The project uses ruff for linting and formatting, and mypy for type checking. Pre-commit hooks run ruff automatically.

ruff check --fix     # lint (make lint)
ruff format          # format
mypy alinemol/       # type-check (make type-check)

Tip

The ruff-format pre-commit hook may reformat files on the first commit attempt, causing it to fail. Re-stage and commit again (do not amend).

Building the documentation

Docs are built with MkDocs + the Material theme, mkdocstrings for API autodoc, mkdocs-jupyter for notebook tutorials, and mike for versioning.

uv pip install -e ".[docs]"

mkdocs serve            # live-reload preview at http://127.0.0.1:8000
mkdocs build --strict   # production build (fails on warnings)

# Convenience wrappers
python build_docs.py serve
python build_docs.py validate   # checks structure + strict build
make docs-serve

Because API pages are auto-generated by importing the package, building the docs requires the runtime dependencies to be importable — install .[all] (or run ./install.sh cpu) alongside .[docs].

Continuous integration & deployment

Workflow Trigger Purpose
ci.yml push / PR to main Tests + ruff on Python 3.9/3.10/3.11
docs.yml push to main, release, manual Build & deploy docs to gh-pages via mike
release.yml GitHub release created Build & publish the package to PyPI

Docs deploy automatically on every push to main that touches docs/, mkdocs.yml, or alinemol/. To deploy manually:

mike deploy --push --update-aliases <version> latest
mike set-default --push latest

Releasing

  1. Update the version in alinemol/_version.py.
  2. Create a new git tag and GitHub release.
  3. The release workflow publishes to PyPI; the docs workflow publishes the matching versioned docs.