Maintain these docs¶
The documentation site is built from Markdown with MkDocs Material and published by GitHub Actions to GitHub Pages. GitHub Pages supports public repositories on GitHub Free, including Free organizations; see GitHub's documentation.
Build locally¶
Use Python 3.12, Go, and make:
python3 -m venv .cache/docs-venv
.cache/docs-venv/bin/python -m pip install -r docs/requirements.txt
make docs
If you manage Python with uv, uv venv --python 3.12 .cache/docs-venv and uv pip install --python .cache/docs-venv/bin/python -r docs/requirements.txt provide the equivalent environment. No paid service, API key, or analytics account is needed.
Open the URL MkDocs prints. Stop the preview with Ctrl-C. After editing source Markdown, rerun make docs to refresh the staged content (or restart make docs-serve). make docs builds site/ and checks local links/anchors. Both site/ and generated staging content stay ignored by Git.
Sources of truth¶
| Content | Edit here |
|---|---|
| Pages/navigation | docs/**/*.md and mkdocs.yml |
| CLI quickstart | Root QUICKSTART.md; copied into the site during preparation |
| Security/contributing/roadmap/support | Corresponding root Markdown file |
| API reference | Go API comments/validation markers, then make generate; rendered from CRD schemas |
| CLI reference | Cobra command help in cmd/replicove; rendered from the built binary |
| Installation manifests | Chart templates, then make manifests |
| Branding | Existing assets/brand files and docs/stylesheets/extra.css |
| Dependency versions | docs/requirements.txt, reviewed together with a successful strict build |
| Executable scenario catalog and release pins | examples/scenarios/catalog.json; the runner and CI enumerate this same catalog |
| Scenario walkthroughs | docs/scenarios/; describe the corresponding fixture's actual assertions and cleanup |
hack/docs.py prepare stages only published documentation, copies brand assets and downloadable examples, rewrites repository-relative links, and builds the API/CLI references. Unpublished design proposals link back to GitHub instead of appearing as current feature documentation. hack/docs.py check checks the built site's local links, assets, and anchors.
Do not edit .cache/docs-src or the generated site. If a field or CLI flag changes, the next build updates the references from implementation. API schema descriptions cannot express every semantic restriction; keep the feature guides and examples current too.
Publication¶
The documentation workflow builds and checks every pull request. Only a successful main build can deploy. The deploy job uses the github-pages environment and the minimal Pages/OIDC permissions; PR builds cannot deploy.
The separate Documentation scenarios workflow runs every catalog variant through ./examples/scenarios/run.sh, using checksum-verified published CLI/chart/manifests and the pinned image digest. It creates only disposable kind clusters. This is repository documentation verification, not a required GitHub Actions integration for users. Changing a tutorial means updating its fixture assertions too; a successful Markdown build alone does not qualify the scenario.
When moving tutorials to another release, review all hashes and the image digest in examples/scenarios/catalog.json, update the pages, and run the full scenario matrix before publication. Preserve historical validation records; add a new sanitized aggregate evidence file and link its exact tested commit/run. Never publish live kubeconfigs, credentials or raw user data in evidence.
The site URL includes /replicove/. Keep site_url, canonical/social metadata, sitemap, and local link checks consistent with that prefix. There is no custom-domain dependency. The repository homepage points at the deployed docs.
Content review¶
For each feature, explain who configures it, a valid YAML example, defaults and limits, observed status, and failure/cleanup behavior. Distinguish actual live evidence from render tests or planned adapters. Update the CLI and YAML entry points together when behavior changes. Verify navigation, search, code copy, dark mode, and narrow-screen readability when changing the theme.
Update the feature map, project status and implementation ledger with every added capability or changed limit. Optional modules also need a late-enable path from a supported earlier release, preservation tests for active resources/state, and cleanup-before-disable instructions. Keep current examples on the released artifact version; historical validation records retain their original version and revision. Generated references and automated link checks complement this review; they cannot establish that prose accurately describes runtime behavior.