Curated autodoc rendering: defaults, xrefs, and responsive layout

CHANGES

@@ -14,10 +14,103 @@ $ pip install --user --upgrade --pre gp-sphinx
 $ uv add gp-sphinx --prerelease allow
 ```
 
-## gp-sphinx 0.0.1 (unreleased)
+## gp-sphinx 0.0.1a18 (unreleased)
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
 
+gp-sphinx 0.0.1a18 ships curated autodoc rendering across the docs
+surface. Parameter signatures now resolve default values to their
+source text — including dataclass `__init__` synthetic defaults,
+sentinel constants by name, and identifier defaults wired up as
+live cross-references to their documented class. Type expressions
+in autodoc field lists route through the same xref pipeline so
+links and chip styling stay consistent with the signature.
+
+The autodoc layout adapts to narrow viewports with a dual-variant
+header: below 52rem the header row stacks instead of squeezing, and
+below 30rem long signatures scroll horizontally instead of wrapping
+mid-identifier. A new `gp-sphinx` cascade layer makes workspace
+overrides win over Furo declaratively, and parameter and field-list
+typography unify into a single metadata-sized band.
+
+A workspace-wide `linkcode_resolve` factory now covers every
+uv/pnpm monorepo package with one registration, pointing at the
+configured live tip branch rather than per-package version tags.
+
+### What's new
+
+#### `gp-sphinx`: 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 (e.g.
+`scope=DEFAULT_OPTION_SCOPE`) instead of `<...object at 0x...>`.
+Long `:value:` text is collapsed so multi-KB constants no longer
+dominate API pages while short useful values stay intact.
+Identifier defaults inside parameter signatures become live
+cross-references to their documented class — the resulting HTML
+matches an inline `:py:class:` role, so hand-written
+`.. py:function::` directives benefit too. (#36)
+
+#### `sphinx-autodoc-typehints-gp`: Canonical Python xrefs in field lists
+
+Type expressions in autodoc field lists route through the same
+xref pipeline as the signature, so links resolve consistently and
+nested types render with chip styling that matches the rest of the
+page. (#36)
+
+#### Autodoc typography polish across the docs surface
+
+Parameter and field-list rows share a unified metadata-sized
+typography band across the autodoc stack. Code chips sit flush
+against generic-type brackets, parameter names use sans-bold while
+monospace is reserved for code identifiers, and root-level scaling
+on wide viewports follows a `clamp()` ramp instead of stepping up
+at a single breakpoint. A new `gp-sphinx` cascade layer makes
+workspace overrides win over Furo declaratively rather than via
+unlayered precedence. (#36)
+
+#### `gp-sphinx`: Workspace-wide `linkcode_resolve` factory
+
+`make_workspace_linkcode_resolve()` is a drop-in `linkcode_resolve`
+for uv/pnpm monorepos — one registration covers every package under
+`packages/` by computing GitHub URLs relative to a `repo_root`. The
+generated URLs always point at a single configurable branch
+(default `main`), since workspace packages carry independent
+versions while the docs site tracks live tip. (#36)
+
+#### `sphinx-ux-autodoc-layout`: Responsive autodoc headers on narrow viewports
+
+Below 52rem the header row stacks instead of squeezing, with the
+type badge pinned beside the signature and the source link
+right-anchored in its toolbar. Below 30rem long signatures scroll
+horizontally rather than wrapping mid-identifier, and the permalink
+reveals on tap for touch users. (#36)
+
+### Bug fixes
+
+#### `sphinx-gp-theme`: TOC font-size override now applies
+
+The override for `--toc-font-size` and `--toc-title-font-size` was
+inert because `gp-furo-tokens` emits the default values on `body`,
+not `:root`. The sidebar TOC now picks up the configured larger
+size. (#36)
+
+#### `sphinx-ux-autodoc-layout`: Mobile header keeps the type badge beside the signature
+
+On narrow viewports the type badge previously wrapped below the
+signature, breaking the eyebrow-style layout. It now stays pinned
+to the left of the signature row. (#36)
+
+#### `sphinx-vite-builder`: CI setup hint no longer requires a root lockfile
+
+The recipe printed by `PnpmMissingError` (and the matching
+README/AGENTS samples) used to include `cache: pnpm`, which fails
+on consumer CI with "Dependencies lock file is not found" 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. (#36)
+
 ## gp-sphinx 0.0.1a17 (2026-05-09)
 
 ### What's new

docs/_ext/api_demo_typehints_gp.py

@@ -0,0 +1,127 @@
+"""Demo module for sphinx-autodoc-typehints-gp showcase.
+
+Exercises every rendering improvement landed on the
+``improved-defaults-reprs`` branch — source-text defaults, dataclass
+factory rendering, long-data truncation, cross-referenced default
+values, field-list xref styling, and the prefix monospace wrapper.
+Each documented object below is referenced from
+``docs/packages/sphinx-autodoc-typehints-gp/examples.md`` so the HTML
+output renders with all transforms active.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+
+
+class CacheScope(enum.Enum):
+    """Where a cached entry lives in the storage hierarchy."""
+
+    Process = "process"
+    Session = "session"
+    Global = "global"
+
+
+class _DefaultRetry:
+    """Sentinel type for the ``retry=`` parameter's default value."""
+
+
+DEFAULT_RETRY: _DefaultRetry = _DefaultRetry()
+"""Sentinel default for ``retry=`` parameters on connection helpers.
+
+When ``retry is DEFAULT_RETRY`` the helper picks a transport-aware
+retry policy from the bound transport's ``retry_policy`` attribute.
+"""
+
+
+SHORT_DEFAULT: str = "admin"
+"""A short, readable module-level constant — renders as-is."""
+
+
+LONG_DEFAULT_RULES: list[tuple[str, str]] = [
+    (f"rule-{i:02d}", f"description for rule number {i}") for i in range(20)
+]
+"""A long ``list[tuple[str, str]]`` used as a documented constant.
+
+The ``repr()`` exceeds the 200-char threshold so the rendered
+``:value:`` collapses to ``<...truncated, N chars>`` instead of
+sprawling across the page.
+"""
+
+
+class ConnectionFailure(Exception):
+    """Raised when a connection attempt fails after exhausting retries."""
+
+
+class Transport:
+    """Documented internal transport — referenced as a parameter type."""
+
+
+@dataclasses.dataclass
+class HookCounters:
+    """Dataclass exercising every default-factory shape.
+
+    Each field uses ``field(default_factory=...)`` with a stdlib
+    container type or a custom callable. After the synthetic-init
+    listener runs, the rendered ``__init__`` signature shows the
+    factory call source text instead of ``=<factory>``.
+    """
+
+    alerts: list[str] = dataclasses.field(default_factory=list)
+    index: dict[str, int] = dataclasses.field(default_factory=dict)
+    names: set[str] = dataclasses.field(default_factory=set)
+    tags: tuple[str, ...] = dataclasses.field(default_factory=tuple)
+    transports: list[Transport] = dataclasses.field(default_factory=list)
+
+
+def open_session(
+    transport: Transport,
+    *,
+    scope: CacheScope = CacheScope.Session,
+    retry: _DefaultRetry = DEFAULT_RETRY,
+    label: str = "default",
+) -> Transport:
+    """Open a session against *transport*.
+
+    The ``scope`` and ``retry`` defaults both reference documented
+    targets on this same page; Stage C's xref transform turns each
+    documented identifier inside a default-value span into a
+    clickable cross-reference using the canonical
+    ``:py:obj:``-styled HTML shape (``<a class="reference internal"
+    href="…"><code class="xref py py-obj">…</code></a>``).
+
+    Parameters
+    ----------
+    transport : Transport
+        The documented transport instance.
+    scope : CacheScope
+        Scope at which session state is cached.
+    retry : _DefaultRetry
+        Retry sentinel; pass an explicit policy to override.
+    label : str
+        Optional label propagated to log records.
+
+    Returns
+    -------
+    Transport
+        The same transport, now bound to the session.
+
+    Raises
+    ------
+    ConnectionFailure
+        Raised when the transport cannot be opened after the retry
+        policy is exhausted.
+    """
+    return transport
+
+
+def with_lambda_default(callback: object = lambda: None) -> None:
+    """Demonstrate Stage C's plain-text fallback for lambda defaults.
+
+    ``ast.parse`` of the default succeeds but the lambda branch isn't
+    handled by the xref transform; the rendered default sits as plain
+    text inside the ``default_value`` span (no spurious ``<code
+    class="xref">`` styling that would imply a missing link target).
+    """
+    del callback

docs/_static/css/custom.css

@@ -1,3 +1,9 @@
+/* All workspace overrides land in @layer gp-sphinx so precedence is
+ * declarative against Furo's @layer components rather than relying
+ * on accidental "unlayered wins." Layer order is established in
+ * gp-furo-theme/web/src/styles/index.css. */
+@layer gp-sphinx {
+
 .sidebar-tree p.indented-block {
   padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0
     var(--sidebar-item-spacing-horizontal);
@@ -109,10 +115,13 @@ article h6 {
  * Uses Furo CSS variable overrides where possible.
  * ────────────────────────────────────────────────────────── */
 
-/* TOC font sizes: override Furo defaults (75% → 87.5%) */
-:root {
-  --toc-font-size: var(--font-size--small);         /* 87.5% = 14px */
-  --toc-title-font-size: var(--font-size--small);   /* 87.5% = 14px */
+/* TOC font sizes: drive from the gp-sphinx-type-metadata role token
+ * (87.5%, ~14px). Declared on `body` because gp-furo-tokens emits
+ * Furo's own --toc-font-size on `body` too — a `:root` override is
+ * silently shadowed for descendants of body. */
+body {
+  --toc-font-size: var(--gp-sphinx-type-metadata);
+  --toc-title-font-size: var(--gp-sphinx-type-metadata);
 }
 
 /* More generous line-height for wrapped TOC entries */
@@ -553,3 +562,5 @@ article > section > blockquote:has(+ .gp-sphinx-package__landing-grid) {
   color: var(--color-foreground-secondary);
   margin: 0.5rem 0 1rem 0;
 }
+
+}  /* end @layer gp-sphinx */

docs/conf.py

@@ -61,7 +61,10 @@
 sys.path.insert(0, str(cwd / "_ext"))  # docs demo modules
 
 import gp_sphinx  # noqa: E402
-from gp_sphinx.config import merge_sphinx_config  # noqa: E402
+from gp_sphinx.config import (  # noqa: E402
+    make_workspace_linkcode_resolve,
+    merge_sphinx_config,
+)
 
 intersphinx_mapping = {
     "py": ("https://docs.python.org/3/", None),
@@ -75,6 +78,11 @@
     source_repository=f"{gp_sphinx.__github__}/",
     docs_url=gp_sphinx.__docs__,
     source_branch="main",
+    linkcode_resolve=make_workspace_linkcode_resolve(
+        repo_root=project_root,
+        github_url=gp_sphinx.__github__,
+        source_branch="main",
+    ),
     extra_extensions=[
         "inline_highlight",
         "package_reference",