Curated autodoc rendering: defaults, xrefs, and responsive layout

[tony]

Summary

• Add curated default-value rendering for autodoc. autodoc_preserve_defaults=True is now the workspace default, and a new listener fills the synthetic-__init__ gap so dataclass parameters render as =[] instead of =<factory> and sentinel constants render as their source name (scope=DEFAULT_OPTION_SCOPE rather than <...object at 0x...>). Long :value: text on module-level constants collapses with a truncation marker so multi-KB defaults no longer dominate API pages.
• Add cross-reference transforms. Identifier defaults inside parameter signatures become live :py:class:-shaped xrefs to their documented class, and type expressions in autodoc field lists route through the same xref pipeline as the signature — links resolve consistently and nested types render with chip styling matching the rest of the page.
• Add responsive autodoc layout. The dual-variant header emits desktop and mobile subtrees under one <dt>; below 52rem the header row stacks instead of squeezing, with the type badge pinned beside the signature and the source link right-anchored in the toolbar. Below 30rem long signatures scroll horizontally instead of wrapping mid-identifier, and the permalink reveals on tap for touch users.
• Add make_workspace_linkcode_resolve() — a drop-in linkcode_resolve factory for uv/pnpm monorepos. One registration covers every package under packages/ by computing GitHub URLs relative to a repo_root, always pointing at one configurable branch (default main) since workspace packages carry independent versions while the docs site tracks live tip.
• Adopt cascade-layer hygiene across the autodoc stack. A new gp-sphinx cascade layer makes workspace overrides win over Furo declaratively; parameter and field-list rows share a unified metadata-sized typography band; code chips sit flush against generic-type brackets; root-level scaling follows a clamp() ramp instead of stepping at a single breakpoint.
• Fix sphinx-gp-theme TOC font-size override. The override was inert because gp-furo-tokens emits the default on body, not :root — moving the override to body restores the configured larger size.
• Fix sphinx-vite-builder CI hint. The recipe printed by PnpmMissingError (and matching README/AGENTS samples) used to include cache: pnpm, which fails on consumer CI when the consumer repo has no root pnpm-lock.yaml. The hint now omits that line with a note explaining when it is safe to add back.

Changes by area

gp-sphinx

• config.py: new make_workspace_linkcode_resolve() factory; merge-config now wires autodoc_preserve_defaults.
• defaults.py: new DEFAULT_AUTODOC_PRESERVE_DEFAULTS = True.

sphinx-autodoc-typehints-gp

Five new private modules implement the default-value pipeline:

• _param_defaults.py — autodoc listener that fills synthetic __init__ defaults (dataclass / attrs / NamedTuple) by walking the real class body, bypassing the upstream listener's inspect.getsource() limitation.
• _data_defaults.py — :value: truncation for long module-level constants.
• _default_xref_transform.py — post-transform that AST-parses default-value text and replaces identifier nodes with pending_xref(reftype='class') wrapped to match an inline :py:class: role's HTML shape.
• _field_xref_transform.py — same canonicalization for type expressions inside autodoc field lists.
• _resolvers.py — shared resolver catalog consumed by both default-value pipelines; private API (no public add_default_resolver until external demand surfaces).

sphinx-ux-autodoc-layout

• _transforms.py: dual-variant header emission. _parse_signature_inputs partitions the original desc_signature children into signature row / badges / source link / parameters; _build_signature_column produces one fresh, independently-parented subtree per variant.
• _static/css/layout.css: container-query-driven @media rules at 52rem and 30rem breakpoints.

Theme / tokens / cross-package CSS

• gp-furo-theme: declares a gp-sphinx cascade layer after Furo's components layer; scaffold uses a clamp() ramp.
• gp-furo-tokens: four --gp-sphinx-type-* role aliases over Furo's font-size scale.
• sphinx-autodoc-api-style, sphinx-autodoc-pytest-fixtures, sphinx-ux-badges: field-list and icon rules relabelled as standalone fallbacks and re-layered into gp-sphinx. Single authoritative grid lives in sphinx-ux-autodoc-layout.

Bug fixes

• sphinx-gp-theme/.../custom.css: TOC font-size override moved from :root to body.
• sphinx-vite-builder/_internal/vite.py + README + AGENTS: drop cache: pnpm from the PnpmMissingError hint and matching CI recipes.

Design decisions

• Workspace defaults, not opt-in. autodoc_preserve_defaults ships flipped on for every consumer rather than as a named option, because the off-state produces unreadable repr text universally. Consumers can still override per-project.
• Dual variants over JS measurement. Both desktop and mobile header subtrees ship in the DOM; CSS container queries pick one. No layout-shift on hydrate; no JS dependency for the responsive cut-over.
• linkcode_resolve factory points at one branch, not version tags. Workspace packages carry independent version strings but the docs site tracks live tip. A per-package version tag would require dispatching by __name__ and miss the live behaviour readers expect when following a "Source" link.
• Resolver catalog stays private. add_default_resolver is not exported; the catalog inside _resolvers.py ships seeded but downstream registration waits for evidence of external demand.

Test plan

• uv run ruff check . — clean
• uv run ruff format --check . — no diff
• uv run mypy — passes across all packages
• uv run pytest -q — full suite passes, including new unit + integration coverage for _param_defaults, _data_defaults, _default_xref_transform, _field_xref_transform, and make_workspace_linkcode_resolve
• rm -rf docs/_build && just build-docs — builds without new warnings or errors
• Dual-variant doctree snapshot tests cover confval, rst:directive, mcp:tool, and large-signature shapes
• HTML integration tests assert presence of gp-sphinx-api-layout--desktop and gp-sphinx-api-layout--mobile siblings under each managed header
• Smoke against libtmux / libvcs / libtmux-mcp after a dev release tag propagates — those consumers pin gp-sphinx and sibling packages by version; the rendering win surfaces only once the workspace tag and sibling pins are updated downstream

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.07407% with 53 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.86%. Comparing base (4e5eb3e) to head (6dd623e).

Files with missing lines	Patch %	Lines
...nx_autodoc_typehints_gp/_default_xref_transform.py	88.05%	16 Missing ⚠️
...src/sphinx_autodoc_typehints_gp/_param_defaults.py	80.82%	14 Missing ⚠️
.../src/sphinx_autodoc_typehints_gp/_data_defaults.py	87.17%	5 Missing ⚠️
...hinx_autodoc_typehints_gp/_field_xref_transform.py	95.65%	4 Missing ⚠️
packages/gp-sphinx/src/gp_sphinx/config.py	92.30%	3 Missing ⚠️
...odoc-layout/src/sphinx_ux_autodoc_layout/_cards.py	94.00%	3 Missing ⚠️
tests/ext/typehints_gp/test_param_defaults.py	96.96%	3 Missing ⚠️
docs/_ext/api_demo_typehints_gp.py	92.30%	2 Missing ⚠️
tests/test_config.py	95.91%	2 Missing ⚠️
...layout/src/sphinx_ux_autodoc_layout/_transforms.py	99.15%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #36      +/-   ##
==========================================
+ Coverage   91.57%   91.86%   +0.28%     
==========================================
  Files         205      219      +14     
  Lines       16814    18035    +1221     
==========================================
+ Hits        15398    16567    +1169     
- Misses       1416     1468      +52     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

Found 1 issue:

1. test_unsupported_default_falls_back_to_plain_text is @pytest.mark.integration but calls build_shared_sphinx_result(...) inline in the test function body rather than via a module-scoped fixture, triggering a fresh Sphinx build per invocation. CLAUDE.md says "No function-scoped Sphinx build fixtures — always module- or session-scoped". The three sibling integration tests in the same file (test_default_value_class_renders_as_xref_link, test_data_attribute_default_links_to_documented_constant, test_cross_module_default_resolves_via_refspecific) all use module-scoped @pytest.fixture(scope="module") wrappers; this one is the outlier.

gp-sphinx/tests/ext/typehints_gp/test_default_xref_integration.py

Lines 294 to 335 in 8dc90a0

	@pytest.mark.integration
	def test_unsupported_default_falls_back_to_plain_text(
	tmp_path_factory: pytest.TempPathFactory,
	) -> None:
	"""Unparseable defaults (lambdas) leave the span as plain text."""
	module_source = textwrap.dedent(
	"""\
	from __future__ import annotations
	def has_lambda_default(callback=lambda: 1) -> None:
	\"\"\"Function with a lambda default.\"\"\"
	"""
	)
	cache_root = tmp_path_factory.mktemp("default-xref-lambda-html")
	scenario = SphinxScenario(
	files=(
	ScenarioFile("lambda_demo.py", module_source),
	ScenarioFile(
	"conf.py",
	_CONF_PY.replace("__SCENARIO_SRCDIR__", SCENARIO_SRCDIR_TOKEN),
	substitute_srcdir=True,
	),
	ScenarioFile(
	"index.rst",
	textwrap.dedent(
	"""\
	Demo
	====
	.. autofunction:: lambda_demo.has_lambda_default
	"""
	),
	),
	),
	)
	result = build_shared_sphinx_result(
	cache_root,
	scenario,
	purge_modules=("lambda_demo",),
	)
	html = read_output(result, "index.html")

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

Found 1 issue:

1. _wrap_prefix_in_paragraph lacks an Examples doctest block (CLAUDE.md says "All functions and methods MUST have working doctests"). Sibling helpers in the same file (_role_class_for_field_name, _enclosing_field_name, _normalize_xref_contnode, _is_em_dash_separator, _is_prose_field) all have doctests; this one was missed. Same omission shape as the F6 batch addressed earlier on this branch.

gp-sphinx/packages/sphinx-autodoc-typehints-gp/src/sphinx_autodoc_typehints_gp/_field_xref_transform.py

Lines 315 to 336 in d08129a

	def _wrap_prefix_in_paragraph(
	paragraph: nodes.paragraph,
	*,
	field_name: str = "",
	) -> bool:
	"""Wrap the prefix children of *paragraph* in a monospace inline.
	The prefix is the run of children before the first em-dash text
	separator. If no separator exists (e.g. ``:rtype:`` /
	``:raises:`` rows whose entire content is a single identifier),
	wraps the full child list.
	Skipped for prose-style fields (``Returns`` / ``Yields`` /
	``Notes`` / ``Examples`` etc.) where the body is free-form
	description text — wrapping those paragraphs would re-style
	ordinary body copy and clash with embedded inline ``<code>``
	spans like ``:any:`None```.
	Returns ``True`` if a wrapper was added, ``False`` if the
	paragraph was already wrapped, lives inside a prose field, or
	otherwise had no eligible content.
	"""

CLAUDE.md rule: https://github.com/git-pull/gp-sphinx/blob/d08129a03d466a5246e51ebbfaabad2519c09c0f/CLAUDE.md#L520-L526

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}