Runbook – Build and Clean Documentation Sites (Public and Academy)¶

Purpose: Ensure the public and academy documentation sites are built correctly, recover from build failures, and clean derived artefacts when needed.
Owner: Platform / Documentation Tooling
Trigger:
- Scheduled docs refresh.
- After significant ADR/runbook/HOWTO changes.
- Following a failed docs build in CI.
Impact:
- Public docs availability and correctness at docs.hybridops.studio (or equivalent).
- Academy docs availability for learners and assessors.
Severity: P3 (non-critical, but important for portfolio and Academy operations).
Pre-reqs:
- Repo access and ability to run make.
- Correct Python environment with MkDocs installed.
- Access to CI logs if debugging CI failures.
Rollback strategy:
- Revert the documentation changes that introduced the failure and rebuild.
- If needed, redeploy the last known good docs artefacts from CI or backup.

Context¶

The documentation build pipeline produces:

Audience-specific doc trees:
deployment/build/docs/public
deployment/build/docs/academy
Static sites:
deployment/build/site/docs-public
deployment/build/site/docs-academy

This runbook standardises how platform engineers:

Run the build.
Validate results.
Clean and recover when generated artefacts become inconsistent or corrupted.

Preconditions and safety checks¶

Before running the steps:

Confirm you are in the correct repository and branch:

git status

Ensure the Python environment is active and has MkDocs:

mkdocs --version

If responding to a CI failure, open the failing job logs and identify:
Which command failed (docs.prepare, docs.build, or a direct mkdocs invocation).
Any specific error messages (e.g. front-matter issues, missing templates).
If you plan to clean generated artefacts, confirm no one is currently deploying from deployment/build/ manually.

Steps¶

1) Run the docs preparation stage

Action: Generate indexes, apply the access model, and create audience-specific doc trees.
Command:
```
make docs.prepare
```
Expected result:
- Command exits with status 0.
- deployment/build/docs/public and deployment/build/docs/academy exist and contain filtered trees.
- control/tools/docs/mkdoc/mkdocs.public.yml and mkdocs.academy.yml are present.
Evidence:
- Save terminal output to output/artifacts/docs/<timestamp>_docs_prepare.log if running as part of a formal change.

2) Build the public and academy sites

Action: Run MkDocs builds for both audiences.
Command:
```
make docs.build
```
Expected result:
- MkDocs reports a successful build for both configs.
- deployment/build/site/docs-public/index.html exists.
- deployment/build/site/docs-academy/index.html exists.
Evidence:
- Save build logs to output/artifacts/docs/<timestamp>_docs_build.log.

3) Local spot-check of public and academy sites

Action: Perform a quick local validation.

Command (optional local preview):

python -m http.server --directory deployment/build/site/docs-public 8000
python -m http.server --directory deployment/build/site/docs-academy 8001

Expected result:
- Public site shows content for a sample ADR, runbook, and HOWTO.
- Academy site shows the same plus any academy-only content where configured.
Evidence:
- Capture screenshots of key pages and attach to the relevant ticket or change record.

4) Clean generated documentation artefacts (when required)

Action: Remove all generated documentation artefacts to recover from inconsistent or corrupted state.
Command:
```
make clean.generated.docs
```
Expected result:
- Generated index READMEs and 000-INDEX.md files are removed from:
- docs/adr, docs/runbooks, docs/howto, docs/ci, docs/showcases.
- Generated by-* views are removed from the same areas.
- deployment/build/docs is removed.
- deployment/build/site/docs-public and deployment/build/site/docs-academy are removed.
- control/tools/docs/mkdoc/mkdocs.public.yml and mkdocs.academy.yml are removed.
Evidence:
- Optionally capture tree deployment/build before and after to show clean-up.

5) Rebuild after clean

Action: Recreate all documentation artefacts from source.
Command:
```
make docs.prepare
make docs.build
```
Expected result:
- Documentation build pipeline completes cleanly.
- Trees and sites are recreated as in steps 1 and 2.
Evidence:
- Updated logs in output/artifacts/docs/ if this is part of a tracked incident or change.

Verification¶

Success criteria:

make docs.prepare and make docs.build complete without errors.
Public and academy sites are reachable in local preview and/or via the deployed URLs.
Spot-checks of ADR, runbook, and HOWTO indices show:
Public content available as expected.
Academy-only content represented correctly (as stubs in public, full content in academy).

For formal verification:

Update associated change or incident tickets with:
Build log locations.
Screenshots or recordings.
Any deviations or follow-ups required.

Post-actions and clean-up¶

Stop any local HTTP servers or mkdocs serve processes used during validation.
If the runbook was triggered by a CI failure:
Update the CI ticket with root cause and resolution.
If the cause was a documentation content issue, link to the fixing commit.
If this runbook is used during a release:
Confirm release notes and documentation pointers reference the updated docs site.
Archive key artefacts under output/artifacts/docs-build/ if part of a formal evidence set.

References¶

Maintainer: HybridOps.Studio License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.