Docs Site

Docs site (properdocs/mkdocs) in personal-os-setup

The config file is properdocs.yml at repo root (not the conventional mkdocs.yml).

The one thing to know before touching anything here

docs_dir: . — the entire repo root is the mkdocs source, not a docs/ subfolder in the usual sense. This is why README.md, CHANGELOG.md, and CONTRIBUTING.md at repo root are directly part of the published site (see the nav: block). It also means any new top-level directory you add to the repo is crawled into the docs build unless excluded. The mkdocs-exclude plugin's glob list in properdocs.yml is what keeps .venv/**, dist/**, .ruff_cache/**, .github/**, etc. out.

If you add a new top-level directory (a cache dir, a build output dir, a new tool's data dir) — add it to that exclude list in properdocs.yml, or it may get published. The mkdocs-same-dir plugin is the other half of making docs_dir: . work at all.

Auto-generated pages — don't hand-maintain these

• scripts/gen_doc_stubs.py (via the gen-files plugin) walks src/**/*.py and generates one API-reference stub per module under package/<path>.md (::: <dotted.module.path> mkdocstrings directive) plus package/SUMMARY.md. Adding a new Python module under src/ automatically gets an API-reference page — no manual nav edit needed. Skips __init__.py files.
• scripts/gen_example_pages.py does the same for docs/examples/**/*.py, pulling each file's module docstring (via ast.get_docstring) into docs/examples/index.md's table. A SyntaxError in an example file is swallowed silently — the build won't fail, the example just loses its description in the index.
• literate-nav (nav_file: SUMMARY.md) drives the API Reference:/examples sub-navs from those generated SUMMARY.md files.

Adding a genuinely new hand-written doc page

Files added under docs/ generally surface automatically via same-dir/mkdocs-material's directory conventions. If it needs a specific slot in the top-level nav, edit properdocs.yml's nav: list directly. Always verify with a local preview — don't assume placement; auto-discovery interacting with docs_dir: . is not always intuitive.

Building/previewing

• make deploy-doc-local → install-dev then properdocs build && properdocs serve — local live preview, run this after any docs change before opening a PR (per CONTRIBUTING.md).
• make deploy-doc-gh → properdocs build && properdocs gh-deploy — pushes directly to the gh-pages branch. This is a remote-mutating action; only run it deliberately (normally CI does this for you, see below), and confirm with the user before running it yourself.

When docs actually go live in CI

main-release.yml deploys docs only if main-release's semantic-release step actually cut a release (if: needs.release.outputs.released == 'true'). A PR containing only docs:/chore:-type commits merged to main will not trigger a docs deploy, even though the docs content changed — because those commit types don't trigger a version bump. If docs need to go live immediately, either bundle the doc change with a releasable commit (feat/fix/perf), or run make deploy-doc-gh manually (after confirming with the user — it pushes to a shared branch).

First-time GitHub Pages setup (not usually needed again): repo Settings → Actions → General → Workflow permissions → "Read and write permissions"; GitHub Pages settings → "Deploy from a branch" → gh-pages.