Maintaining the documentation

The website is built from function docstrings, pages under docs/, and notebooks under examples/.

Document a function

Write a NumPy-style docstring directly below the function definition:

def my_function(data, threshold=0.5):
    """Describe what the function does in one sentence.

    Parameters
    ----------
    data : pandas.DataFrame
        Explain the expected rows, columns, and important constraints.
    threshold : float, default=0.5
        Explain how the parameter changes the calculation.

    Returns
    -------
    pandas.Series
        Explain the returned values and their index.

    Raises
    ------
    ValueError
        Explain when this error is raised.
    """

If the function is newly public, export it from src/cytogater/__init__.py and add an autofunction entry to docs/api.md:

.. autofunction:: cytogater.my_function

Sphinx reads the function signature and docstring each time the website is built; there is no separate API text to keep in sync.

Update the full pipeline tutorial

Activate the package environment, install the current checkout, and execute the canonical notebook in place:

conda activate cytogater-python
python -m pip install -e ".[plot,notebook]"
jupyter nbconvert \
  --to notebook \
  --execute \
  --inplace \
  --ExecutePreprocessor.timeout=1200 \
  --ExecutePreprocessor.allow_errors=False \
  examples/full_pipeline.ipynb

Review every cell and confirm there are no errors or unexpected warnings. The file docs/full_pipeline.ipynb is a symbolic link to this notebook, so the website automatically uses the newly saved tables and figures.

The website does not re-execute this notebook on GitHub because the source R demo data lives in a sibling repository. It does execute the self-contained docs/tutorial.md example on every build.

Preview the website

Install the documentation tools and run a strict build:

python -m pip install -e ".[doc]"
sphinx-build -b html -W --keep-going docs docs/_build/html
python -m http.server --directory docs/_build/html 8000

Open http://localhost:8000 and inspect the tutorial and API reference.

Publish

Commit the source files and push them to main:

git add docs examples/full_pipeline.ipynb src/cytogater README.md pyproject.toml
git commit -m "Update API documentation and full pipeline tutorial"
git push origin main

The docs GitHub Actions workflow builds and deploys the website.