Development#

This page explains how to run the test suite, configure pre-commit hooks, and build the documentation locally.

For environment setup and installation instructions see the Installation page.

Running the tests#

The test suite uses pytest with coverage support. The full configuration lives in pyproject.toml under [tool.pytest.ini_options].

Run all tests#

python -m pytest

pytest is configured with -v (verbose), --strict-markers, and --disable-warnings by default, so you will see one line per test case.

Run a single test#

Specify the file, class, and method separated by :::

python -m pytest tests/test_altx.py::TestTrain::test_train_populates_ps_for_all_rlk

Run with coverage#

python -m pytest --cov

Coverage is measured over the altx/ package (configured under [tool.coverage.run]). The tests/ directory is excluded from the report.

Test structure#

File	What it tests
`tests/test_altx.py`	All public methods of `Altx` — init validation, embed, train, save/load, multiply, transform, transform_set, save features, header generation, print_number_of_laws
`tests/test_extract_methods.py`	All extraction methods in `ExtractMethods` — excess_kurtosis, nth_moment, and the main extract dispatcher

Pre-commit hooks#

Pre-commit hooks run automatically on every git commit and enforce code quality. They are configured in .pre-commit-config.yaml.

Install the hooks#

Run this once after cloning the repository:

pre-commit install

After that, git commit will trigger all hooks automatically on the staged files.

Run hooks manually#

On specific files:

pre-commit run --files altx/altx.py altx/extract_methods.py

On the entire repository:

pre-commit run --all-files

Hooks that are configured#

Hook	Tool	What it checks / fixes
`trailing-whitespace`	pre-commit-hooks	Trims trailing whitespace from every line
`end-of-file-fixer`	pre-commit-hooks	Ensures files end with exactly one newline
`check-yaml`	pre-commit-hooks	Validates YAML syntax
`check-json`	pre-commit-hooks	Validates JSON syntax
`check-merge-conflict`	pre-commit-hooks	Blocks committing unresolved merge conflict markers
`check-added-large-files`	pre-commit-hooks	Rejects files larger than 5 MB
`no-commit-to-branch`	pre-commit-hooks	Prevents direct commits to `main` or `master`
`black`	Black	Auto-formats Python files to 88-character lines
`nbqa-black`	nbQA + Black	Applies Black formatting to Jupyter notebooks
`ruff-format`	Ruff	Applies Ruff’s formatter (compatible with Black)
`ruff-check`	Ruff	Lints and auto-fixes import ordering, bugbear rules, docstring style, and more (see below)
`nbqa-ruff`	nbQA + Ruff	Applies Ruff linting to Jupyter notebooks
`mypy`	Mypy	Strict type checking (Python 3.12 target, `strict = true`), production code only
`pydocstyle`	pydocstyle	Enforces NumPy docstring convention

Ruff rule groups#

The following Ruff rule groups are active (see [tool.ruff.lint] in pyproject.toml):

Code	Group	Purpose
`E`	pycodestyle	Style errors (line length, whitespace, etc.)
`F`	pyflakes	Undefined names, unused imports
`I`	isort	Import ordering
`N`	pep8-naming	Class, function, and variable naming
`D`	pydocstyle	Docstring presence and formatting
`UP`	pyupgrade	Modernise Python syntax
`B`	flake8-bugbear	Common bugs and design issues
`C4`	flake8-comprehensions	Idiomatic comprehensions
`SIM`	flake8-simplify	Unnecessarily complex code
`RUF`	Ruff-specific	Ruff’s own additional rules

Ignored rules: E741 (ambiguous names), N802/N803/N806/N814 (non-lowercase identifiers and camelcase constants). Test files additionally ignore all D rules.

Branch protection#

The no-commit-to-branch hook blocks direct commits to main and master. Always create a feature branch first:

git switch -c feature/my-change

Building the documentation#

The documentation is built with Sphinx using the pydata_sphinx_theme. The source files live in docs/source/ and the built HTML is written to docs/_build/html/.

Install documentation dependencies#

pip install -e ".[docs]"

This installs:

Package	Purpose
`sphinx`	Core documentation builder
`pydata-sphinx-theme`	HTML theme
`myst-parser`	Allows writing documentation pages in Markdown (`.md`)
`sphinx-autodoc-typehints`	Renders Python type annotations in the API reference
`numpydoc`	NumPy docstring support
`sphinx-copybutton`	Adds a copy button to code blocks
`sphinx-design`	Additional layout components (grids, cards, tabs)

Build HTML locally#

The quickest way is to use the Makefile that ships in the docs/ directory:

cd docs
make html

The output is written to docs/build/html/. Open docs/build/html/index.html in a browser to view the result. Run make clean first if you want to discard the cached build and start from scratch.

Alternatively, call sphinx-build directly from the repository root (this is what CI uses and writes to a different output directory):

sphinx-build -b html docs/source docs/_build/html

To treat all warnings as errors (mirrors CI behaviour):

sphinx-build -W -T -b html docs/source docs/_build/html

Documentation structure#

docs/
├── source/
│   ├── conf.py          ← Sphinx configuration (theme, extensions, version)
│   ├── index.rst        ← Top-level table of contents
│   ├── installation.md  ← Installation instructions
│   ├── usage.md         ← Usage guide and examples
│   ├── development.md   ← This page
│   └── api/
│       ├── modules.rst  ← Auto-generated module list
│       └── altx.rst     ← API reference (autodoc directives)
└── _build/
    └── html/            ← Generated HTML output (not committed)

conf.py derives the package version from the latest git tag via setuptools-scm. If no tag is found, it falls back to the installed package version, and then to "0.0.0".

Continuous integration#

The documentation is built automatically on every push via the .github/workflows/build-docs.yml workflow. The workflow:

Builds the HTML documentation.
Uploads it as a GitHub Actions artifact (html-docs).
On pushes to master or version tags (v*), deploys the artifact to GitHub Pages via the peaceiris/actions-gh-pages action.

Continuous integration overview#

Workflow	File	Trigger	What it does
Python tests	`tests.yml`	Every push and PR	Runs pytest with coverage on Python 3.12, 3.13, and 3.14; uploads a coverage badge on pushes to `halmosb/altx`
Pre-commit check	`pre-commit.yml`	Every push and PR	Runs all pre-commit hooks (`--all-files`) except `no-commit-to-branch`
Build and Deploy Docs	`build-docs.yml`	Every push, PRs to main/master	Builds Sphinx HTML; deploys to GitHub Pages on `master` or version tags

All CI jobs run in the custom Docker image ghcr.io/halmosb/docker-builder/python:3.14-cpu-v0.3.4, which pre-installs the required Python version and PyTorch CPU build, see github.com/halmosb/docker-builder for more details.