Refactor for improved autodoc typings, UX (#18)

gp-sphinx moves from a shared-config package to an integrated autodoc
design system.  Twelve packages in three dependency tiers share one
badge palette, one layout pipeline, one typehint renderer, and one
CSS vocabulary — so Python APIs, argparse CLIs, pytest fixtures,
Sphinx config values, docutils directives, and FastMCP tools all
render like they belong together.  Four reader-facing sidebar buckets
(Domain Packages / UX / Utils / Internal) give a separate navigation
axis on top of the dependency map.

- **Two new foundation packages** — `sphinx-ux-autodoc-layout`
  introduces componentized autodoc output (card regions, parameter
  folding, managed signatures); `sphinx-autodoc-typehints-gp` is a
  single-package replacement for `sphinx-autodoc-typehints` +
  `sphinx.ext.napoleon` that resolves annotations statically at
  build time with no monkey-patching.

- **`argparse` Sphinx domain** — `sphinx-autodoc-argparse` now ships
  a real `Domain` subclass.  Programs, options, subcommands, and
  positional arguments each have their own `ObjType` and
  `:argparse:*` xref role; two auto-generated indices give an
  alphabetical programs list and a program-grouped options list.
  `:option:` / `std:cmdoption` continues to resolve for intersphinx
  consumers.  `Framework :: Sphinx :: Domain` classifier added.

- **Unified visual vocabulary** — every class, directive, and CSS
  custom property is namespaced under a single `gp-sphinx-*`
  two-tier BEM root (`gp-sphinx-badge`, `gp-sphinx-fastmcp__*`,
  etc.).  The six opaque per-package prefixes (`sab-`, `smf-`,
  `spf-`, `api-`, `gas-`, `gal-`) are retired and the duplicate
  palettes that hid behind them collapse to one source of truth.

- **Sphinx 8.1 floor + typed domains** — workspace-wide floor bump
  unlocks `env.domains.<name>_domain` typed accessors; `t.cast` /
  `# type: ignore` workarounds across the domain-access paths retire
  as a result.

- **Rebuilt test harness** — a shared `SphinxScenario` cache keyed
  by content-hash digest reuses identical builds across tests.  Most
  cases now run against the docutils doctree directly; a
  syrupy-based snapshot layer locks doctree structure, rendered
  HTML, and warning output with path and ANSI normalization built
  in.

- **Codified workspace conventions** — `AGENTS.md` now documents the
  `gp-sphinx-*` BEM namespace, the rule that any test which
  constructs a `Sphinx` app (including `buildername="dummy"`) gets
  `@pytest.mark.integration`, and the per-package CSS
  self-containment contract.

Breaking changes:

Workspace package renames — update imports and `extensions =` lists
downstream; old names keep redirecting for docs URLs via
`docs/redirects.txt`:

| Old                        | New                            |
|----------------------------|--------------------------------|
| `sphinx-argparse-neo`      | `sphinx-autodoc-argparse`      |
| `sphinx-gptheme`           | `sphinx-gp-theme`              |
| `sphinx-autodoc-badges`    | `sphinx-ux-badges`             |
| `sphinx-autodoc-layout`    | `sphinx-ux-autodoc-layout`     |
| `sphinx-typehints-gp`      | `sphinx-autodoc-typehints-gp`  |

Directive renames:

| Old                       | New                       |
|---------------------------|---------------------------|
| `autosphinxconfig-index`  | `autoconfigvalue-index`   |
| `fastmcp-toolsummary`     | `fastmcp-tool-summary`    |
| `doc-pytest-plugin`       | `auto-pytest-plugin`      |

Runtime floor bumped to Sphinx 8.1 (was 7.x).

See also:
- Gallery: https://gp-sphinx.git-pull.com/gallery.html
- Architecture: https://gp-sphinx.git-pull.com/architecture.html
- What's new: https://gp-sphinx.git-pull.com/whats-new.html

Author: tony

.github/workflows/tests.yml

@@ -124,13 +124,17 @@ jobs:
         target:
           - root-install
           - gp-sphinx
-          - sphinx-gptheme
+          - sphinx-gp-theme
           - sphinx-fonts
-          - sphinx-argparse-neo
+          - sphinx-autodoc-argparse
           - sphinx-autodoc-docutils
           - sphinx-autodoc-sphinx
           - sphinx-autodoc-pytest-fixtures
           - sphinx-autodoc-api-style
+          - sphinx-autodoc-fastmcp
+          - sphinx-autodoc-typehints-gp
+          - sphinx-ux-badges
+          - sphinx-ux-autodoc-layout
     steps:
       - uses: actions/checkout@v6
 

.gitignore

@@ -218,6 +218,9 @@ docs/_static/css/fonts.css
 # Playwright MCP
 .playwright-mcp/
 
+# Repo-local pytest mirror (do not track — validator-only)
+out/
+
 # Misc
 .vim/
 *.lprof