Architecture¶
Workspace packages organized in tiers. Lower layers never depend on higher ones — autodoc extensions consume shared infrastructure, and the presentation layer wires everything together for downstream projects.
The sidebar groups these packages into navigation buckets (Domain Packages, UX, Utils, Internal) — a reader-facing grouping that is orthogonal to the dependency-ordered tier map below.
Tier 2: Autodoc extensions¶
Domain-specific autodoc extensions that consume Tier 1 and add project-specific rendering logic. Each ships directives that generate documentation from a particular source-construct family:
Subject: standard Python.
Directives: autofunction, autoclass, automodule.
Subject: argparse parsers — programs, options, subcommands, positionals.
Directives: argparse (custom argparse domain).
Subject: docutils directives and roles.
Directives: autodirective, autorole.
Subject: FastMCP tools, prompts, resources.
Directives: fastmcp-tool, fastmcp-tool-summary.
Subject: pytest fixtures (extends the py domain).
Directives: autofixture, autofixtures, auto-pytest-plugin.
Subject: Sphinx config values.
Directives: autoconfigvalue, autoconfigvalues.
Each autodoc extension calls app.setup_extension() to auto-register its
infrastructure dependencies — downstream projects only need to add the
package to their extensions list.
Tier 3: Theme and coordinator¶
Package |
Role |
|---|---|
Coordinator. |
|
Furo-based theme with CSS variables and SPA navigation. |
|
Tailwind v4 port of upstream Furo for git-pull projects. |
|
IBM Plex via Fontsource — preloaded web fonts. |
Build tooling¶
Cross-cutting build utilities that operate outside the docs-build
runtime — one is a PEP 517 build
backend invoked when wheels are produced; the other is an opt-in
extension that drives the Vite watcher during sphinx-autobuild.
Both let theme authors keep build artefacts (static/styles/*.css,
static/scripts/*.js) out of VCS while still shipping working wheels
and seamless live-reload during authoring.
PEP 517 build backend (or
hatchling build hook via [tool.hatch.build.hooks.vite]) that runs
pnpm exec vite build before delegating wheel/sdist construction to
hatchling. Also a Sphinx extension that auto-orchestrates
vite build --watch during sphinx-autobuild and one-shot
vite build during plain sphinx-build.
Source builds error loudly without pnpm/Node; wheels ship turn-key.
Publishable for use outside this workspace — any vite + Sphinx
project can adopt either activation path without depending on the
gp-sphinx coordinator.
How the tiers connect¶
Every autodoc extension shares the same badge palette, the same componentized HTML output structure, and the same type annotation pipeline — so Python APIs, pytest fixtures, Sphinx config values, docutils directives, and FastMCP tools all look like they belong together.
This is the one autodoc design system principle: a change to the shared infrastructure propagates instantly and consistently across every autodoc extension in the workspace.