Developer Guide¶

This page captures the standard development workflow.

Environment Setup¶

git clone https://github.com/Byzpy/byzpy.git
cd byzpy
python -m venv .venv
source .venv/bin/activate
pip install -e python[dev]
pip install -e python[gpu]            # optional CUDA extras
pip install -r docs/requirements.txt  # to build docs

Linting & Tests¶

cd python
pytest
pytest --cov=byzpy --cov-report=term-missing   # coverage goal ≥ 80%

Documentation¶

Building Documentation¶

Install documentation dependencies:

pip install -r docs/requirements.txt

Build HTML documentation:

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

Or from the repository root:

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

Viewing Documentation Locally¶

Option 1: Open HTML file directly

open docs/_build/html/index.html        # macOS
xdg-open docs/_build/html/index.html    # Linux
start docs/_build/html/index.html       # Windows

Option 2: Use HTTP server (recommended)

cd docs/_build/html
python -m http.server 8000
# Then visit http://localhost:8000 in your browser

Option 3: Live reload during development

pip install sphinx-autobuild
sphinx-autobuild docs/source docs/_build/html

This automatically rebuilds when files change and serves at http://127.0.0.1:8000.

Documentation Contribution¶

See docs/CONTRIBUTING.md for detailed guidelines on:

Documentation structure
Writing style guidelines
How to add new documentation
Documentation review checklist

Documentation Quality Checks¶

Before submitting documentation changes:

# Build with warnings as errors
sphinx-build -W -b html docs/source docs/_build/html

# Check for broken links
sphinx-build -b linkcheck docs/source docs/_build/linkcheck

# Verify all examples work
pytest docs/source/  # if examples are in test files

Submitting Changes¶

Fork + branch.
Update docs/tests when touching public APIs.
Run pytest and sphinx-build.
Open a PR with a clear summary, test output, and coverage notes.