Developer Guide

This guide collects the repository-maintainer workflows for pymizer: local development installs, documentation builds, package checks, and GitHub Pages publishing.

Development Install

From the repository root:

python3 -m venv python/.venv
python/.venv/bin/python -m pip install --upgrade pip
python/.venv/bin/python -m pip install -e './python[dev]'

Install the R package separately:

install.packages("mizer")

For CI environments, install Python and R first, then install mizer, and only after that install pymizer with pip.

Build The Docs

This website is built with Quarto, and the API reference pages are generated by quartodoc from the Python package source:

source python/.venv/bin/activate
cd python
quartodoc build --config docs/_quarto.yml
QUARTO_PYTHON="$(pwd)/.venv/bin/python" quarto render docs

For live preview during editing:

source python/.venv/bin/activate
cd python
quartodoc build --config docs/_quarto.yml --watch
QUARTO_PYTHON="$(pwd)/.venv/bin/python" quarto preview docs

quartodoc build reads docs/_quarto.yml and writes the generated API pages into docs/api/. Quarto then renders the hand-written .md and .qmd pages alongside that generated reference.

Those generated docs/api/ files are local build artifacts, so rerun quartodoc build whenever you need to preview, render, or publish the site.

Set QUARTO_PYTHON to the repository virtualenv so executable articles run against the same Python, rpy2, and R-backed pymizer environment as the library itself.

Build And Check Distributions

Before publishing, build both package formats and run the metadata checks:

source python/.venv/bin/activate
cd python
python -m build
python -m twine check dist/*

Publish To GitHub Pages

For the pymizer site, the simplest publish path is to let Quarto render the site and push the output to the gh-pages branch for you.

First, make sure the GitHub repository is configured to serve Pages from the gh-pages branch:

  1. Open the repository on GitHub.
  2. Go to Settings -> Pages.
  3. Set the source to Deploy from a branch.
  4. Choose the gh-pages branch and the / (root) folder.

Then publish from your local checkout:

source python/.venv/bin/activate
cd python
quartodoc build --config docs/_quarto.yml
QUARTO_PYTHON="$(pwd)/.venv/bin/python" quarto publish gh-pages docs

Quarto will:

  • render the site from docs/
  • create or update the gh-pages branch
  • push the rendered _site/ output to GitHub Pages

If you prefer to inspect the rendered site before publishing, render first and then publish:

source python/.venv/bin/activate
cd python
quartodoc build --config docs/_quarto.yml
QUARTO_PYTHON="$(pwd)/.venv/bin/python" quarto render docs
QUARTO_PYTHON="$(pwd)/.venv/bin/python" quarto publish gh-pages docs

After the push completes, GitHub Pages will usually update the public site within a minute or two.