Skip to content

Docs Stack

This page defines the documentation tooling used by WorldFlux and explains why each library is included.

Purpose

  • Keep docs authoring simple (MkDocs + Markdown).
  • Keep API docs synchronized with code (mkdocstrings).
  • Catch documentation regressions early in CI (strict build + external link checks).
  • Stay pragmatic: adopt only what is needed for the current project size.

Adopted Libraries (WorldFlux)

Library Why it is used
mkdocs Static docs site generator for the full docs set
mkdocs-material Production-ready theme and navigation UX
mkdocstrings[python] Autogenerated API reference from Python docstrings
mkdocs-autorefs Automatic cross-references between pages and symbols
mkdocs-redirects Safe URL/path migrations for docs pages
mkdocs-git-revision-date-localized-plugin Page update metadata from git history
mkdocs-minify-plugin Smaller generated HTML output
pymdown-extensions Markdown quality-of-life features (tabs, fences, details)

Not Adopted in This Revision (and why)

Candidate Deferred reason
Sphinx migration Not required for current docs scale; higher maintenance cost
Astro / Docusaurus migration Would add a second docs stack without immediate ROI
Vale style linting Useful but out of scope for the current minimal change set
Snippet execution pipeline Valuable, but deferred to keep CI/runtime cost low

Standard Commands

uv sync --extra docs
uv run mkdocs serve
uv run mkdocs build --strict

Policy

  • Runtime API/architecture is unchanged by docs-tooling updates.
  • Docs dependencies must remain minimal and clearly justified.
  • New docs tooling should be added only when a concrete docs quality gap exists.