Documentation Release Workflow

This workflow describes how to manually publish the Buffalo Wings documentation to the pages repository. Use it when the normal hosted documentation publishing path is unavailable or when the documentation needs to be updated manually.

Goal

The goal is to copy the built HTML documentation from this repository into the BuffaloWingsDocs directory of the organization pages repository and publish that update.

Prerequisites

Before starting, make sure:

this repository is up to date,
the documentation builds successfully,
you have push access to the pages repository,
and you are working from a parent directory where both repositories can exist side by side.

1. Ensure The Project Repository Is Current

Make sure the local project repository is up to date:

git checkout main
git pull --ff-only
git tag --list | tail

If you need to refresh tags, run:

git fetch --tags

2. Read The Current Release Version

Read the current project version from pyproject.toml:

VERSION_TAG="v$(python - <<'PY'
import tomllib
with open("pyproject.toml", "rb") as f:
    print(tomllib.load(f)["project"]["version"])
PY
)"
echo "Publishing documentation for ${VERSION_TAG}"

3. Build The Documentation

Build the documentation from the repository root:

./scripts/build_docs.sh

This should create the HTML site under sphinx/build/html.

All Sphinx-related actions in this repository are expected to run through uv. Do not invoke sphinx-build or make html directly outside the repository-managed workflow.

To verify the build output exists:

test -f sphinx/build/html/index.html

4. Prepare The `pages` Repository

From the parent directory of this repository, clone the pages repository if needed:

git clone git@codeberg.org:BuffaloHerd/pages.git

If you already have a local clone, update it instead:

cd pages
git checkout main
git pull --ff-only
cd ..

At this point, the directory layout should look like this:

BuffaloWings/
pages/

5. Replace The Published Documentation

Make sure you run this step from the parent directory that contains both repositories. Remove the existing published documentation directory and replace it with the new build output:

rm -fr pages/BuffaloWingsDocs
mkdir -p pages/BuffaloWingsDocs
cp -a BuffaloWings/sphinx/build/html/. pages/BuffaloWingsDocs/

6. Review And Publish The `pages` Change

Commit and push the documentation update from the pages repository:

cd pages
git add BuffaloWingsDocs
git status
git commit -m "Update Buffalo Wings docs for ${VERSION_TAG}"
git push -u origin HEAD

7. Verify The Published Site

After the push completes, verify that the hosted documentation updates successfully and that the main landing page loads as expected.

At minimum, check:

the documentation home page,
the examples page,
and one or two API reference pages.