documenteer 2.5.0b2__tar.gz → 2.5.0b3__tar.gz

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.5.0b2
+Version: 2.5.0b3
 Summary: Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.
 License-Expression: MIT
 Project-URL: Homepage, https://documenteer.lsst.io

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/changelog.d/20260722_000000_jonathan_DM_55387_intersphinx_cache.md

@@ -1,3 +1,3 @@
 ### New features
 
-- Documentation builds now prefetch intersphinx object inventories from Ook's inventory cache service, so builds no longer depend on third-party site availability to resolve cross-references. The new `documenteer.ext.intersphinxcache` extension — registered by both the user-guide and technote configuration presets — runs before `sphinx.ext.intersphinx` processes its mapping: it fetches each entry's `objects.inv` from the service, writes it to the build directory, and rewrites that entry's inventory location to the local file. Target URIs are left unchanged, so resolved links still point at the upstream sites. Prefetching authenticates with a bearer token from `OOK_TOKEN`; when the token is unset (fork pull requests, local builds) the extension is a complete no-op, and any per-inventory service failure (unauthorized, unreachable, server error, timeout) falls back to a direct origin fetch, reported at the `INFO` log level (not as a warning, so warnings-as-errors `-W` builds don't fail on graceful service degradation), so an Ook outage can never make a build worse than stock intersphinx. New `[sphinx.intersphinx_cache]` settings in `documenteer.toml` configure the integration for guides (`use_service`, `service_url`); technotes use the defaults and can override the corresponding `documenteer_intersphinx_cache_*` values in `conf.py` after the preset import.
+- Documentation builds now prefetch intersphinx object inventories from Ook's inventory cache service, so builds no longer depend on third-party site availability to resolve cross-references. The new `documenteer.ext.intersphinxcache` extension — registered by both the user-guide and technote configuration presets — runs before `sphinx.ext.intersphinx` processes its mapping: it fetches each entry's `objects.inv` from the service, writes it to the build directory, and rewrites that entry's inventory location to the local file. Target URIs are left unchanged, so resolved links still point at the upstream sites. Prefetching authenticates with a bearer token from `OOK_TOKEN`; when the token is unset (fork pull requests, local builds) the extension is a complete no-op, and any per-inventory service failure (unauthorized, unreachable, server error, timeout) falls back to a direct origin fetch, reported at the `INFO` log level (not as a warning, so warnings-as-errors `-W` builds don't fail on graceful service degradation), so an Ook outage can never make a build worse than stock intersphinx. New `[sphinx.intersphinx.cache]` settings in `documenteer.toml` configure the integration for guides (`use_service`, `service_url`); technotes use the defaults and can override the corresponding `documenteer_intersphinx_cache_*` values in `conf.py` after the preset import.

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/changelog.d/20260723_000000_jonathan_DM_55600_intersphinx_cache_ttl.md

@@ -1,3 +1,3 @@
 ### New features
 
-- Prefetched intersphinx inventories are now cached on disk with a short time-to-live (the new `disk_cache_ttl` setting under `[sphinx.intersphinx_cache]`, default 600 seconds; `0` disables it), so rapid successive local rebuilds reuse the cached `objects.inv` without contacting Ook at all. Once the TTL expires, Documenteer revalidates conditionally: it sends the stored ETag as an `If-None-Match` header, and a `304 Not Modified` reuses the on-disk copy with no inventory body transferred (a `200 OK` replaces it). Technotes can override the TTL through `documenteer_intersphinx_cache_disk_cache_ttl` in `conf.py`.
+- Prefetched intersphinx inventories are now cached on disk with a short time-to-live (the new `disk_cache_ttl` setting under `[sphinx.intersphinx.cache]`, default 600 seconds; `0` disables it), so rapid successive local rebuilds reuse the cached `objects.inv` without contacting Ook at all. Once the TTL expires, Documenteer revalidates conditionally: it sends the stored ETag as an `If-None-Match` header, and a `304 Not Modified` reuses the on-disk copy with no inventory body transferred (a `200 OK` replaces it). Technotes can override the TTL through `documenteer_intersphinx_cache_disk_cache_ttl` in `conf.py`.

documenteer-2.5.0b3/changelog.d/20260813_000000_jonathan_DM_55690_alias_metadata_fragments.md

@@ -0,0 +1,3 @@
+### Bug fixes
+
+- `documenteer.ext.autotypes` no longer warns about the reference targets Sphinx synthesizes out of a *type alias's own* `Annotated` value. Safir's `type IvoaIsoDatetime = Annotated[datetime, BeforeValidator(...), PlainSerializer(..., when_used="json")]` is the shape: Sphinx renders the alias's value onto its page (and into every signature the alias annotates), stringifying each dataclass metadata field, and then unparses the result into a reference per fragment — leaking `PydanticUndefined` (the repr of `BeforeValidator`'s sentinel default) and `json` (the unquoted string value of `when_used`) as nitpick warnings. The existing fragments rung could not cover them because it rebuilds the fragments of a documented *class's* metadata, while an alias page carries no `py:class` context at all. A module-scoped sibling index now rebuilds the fragments that the `Annotated` aliases of the reference's `py:module` context module render — both a PEP 695 `type` statement and an assignment-style `Annotated` alias — and degrades those names to unlinked literal text. Like its class-scoped sibling it resolves nothing and is consulted only after every resolution rung has already failed, so a name no alias of that module renders — a typo of a real fragment included — keeps warning, and a fragment of one module's alias does not degrade under another module's context.

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/docs/guides/toml-reference.rst

@@ -503,7 +503,7 @@ The values are URLs to the root of Sphinx documentation projects.
 
 See the Intersphinx_ documentation for details on linking to other Sphinx projects.
 
-[sphinx.intersphinx_cache]
+[sphinx.intersphinx.cache]
 ==========================
 
 |optional|
@@ -543,7 +543,7 @@ Set this to ``false`` as an escape hatch to disable prefetching so Intersphinx_
 
 .. code-block:: toml
 
-   [sphinx.intersphinx_cache]
+   [sphinx.intersphinx.cache]
    use_service = false
 
 With ``use_service = false`` the service is never contacted, even when an ``OOK_TOKEN`` is set.
@@ -576,7 +576,7 @@ Set ``disk_cache_ttl`` to ``0`` to disable this fast path so every build revalid
 
 .. code-block:: toml
 
-   [sphinx.intersphinx_cache]
+   [sphinx.intersphinx.cache]
    disk_cache_ttl = 0
 
 The TTL governs only the client-to-Ook hop; whether Ook's own cached copy is current relative to the origin site remains Ook's concern.

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/docs/sphinx-extensions/autotypes.rst

@@ -136,6 +136,11 @@ The annotated *type* is deliberately excluded, so it keeps following the ordinar
 
 .. [#source] ``sphinx.util.typing.get_type_hints`` falls back to a class's raw ``__annotations__`` when evaluating them raises, and autodoc first copies each base class's *source* annotations onto the class — which is enough to make that fallback fire on a Pydantic model. Under ``from __future__ import annotations`` those raw annotations are :pep:`563` strings, so the annotation is rendered exactly as written.
 
+The same fragment family reaches a **type alias's own page**, where the reference carries no ``py:class`` context for that rung to read — only the ``py:module`` of the module the alias is documented from.
+Safir's ``type IvoaIsoDatetime = Annotated[datetime, BeforeValidator(…), PlainSerializer(…, when_used="json")]`` is the case that motivated this: Sphinx renders the alias's whole value onto its stub page — and into every signature the alias annotates, since an assignment-style alias knows neither its own name nor its module — leaking ``PydanticUndefined``, the repr of ``BeforeValidator``\ ’s sentinel default, and a bare ``json`` from the unquoted ``when_used`` value.
+A module-scoped sibling index therefore rebuilds the fragments that the ``Annotated`` aliases of the reference's ``py:module`` context render, covering both alias spellings: a :pep:`695` ``type`` statement whose value is (or contains) an ``Annotated`` form, and an assignment-style ``Annotated`` alias.
+It resolves nothing either, and is consulted only after the class-scoped rung has failed as well, so the guardrail is the same one module out — a name that no alias of that module renders keeps warning, and a fragment of one module's alias does not degrade under another module's context.
+
 Anything else is left alone, so genuine mistakes (a typo'd module path that fails to import, a reference to something in this project's public API that should be exported and documented but isn't) still surface as nitpick warnings.
 
 Sub-extensions

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/src/documenteer/conf/_toml.py

@@ -171,14 +171,6 @@ class ProjectModel(BaseModel):
     openapi: OpenApiDocsModel | None = Field(None)
 
 
-class IntersphinxModel(BaseModel):
-    """Model for Intersphinx configurations in documenteer.toml."""
-
-    projects: dict[str, HttpUrl] = Field(
-        description="Mapping of projects and their URLs.", default_factory=dict
-    )
-
-
 class IntersphinxCacheModel(BaseModel):
     """Model for the Ook intersphinx inventory cache configuration in
     documenteer.toml.
@@ -214,6 +206,16 @@ class IntersphinxCacheModel(BaseModel):
     )
 
 
+class IntersphinxModel(BaseModel):
+    """Model for Intersphinx configurations in documenteer.toml."""
+
+    projects: dict[str, HttpUrl] = Field(
+        description="Mapping of projects and their URLs.", default_factory=dict
+    )
+
+    cache: IntersphinxCacheModel = Field(default_factory=IntersphinxCacheModel)
+
+
 class LinkCheckModel(BaseModel):
     """Model for linkcheck builder configurations in documenteer.toml."""
 
@@ -354,10 +356,6 @@ class SphinxModel(BaseModel):
 
     intersphinx: IntersphinxModel = Field(default_factory=IntersphinxModel)
 
-    intersphinx_cache: IntersphinxCacheModel = Field(
-        default_factory=IntersphinxCacheModel
-    )
-
     linkcheck: LinkCheckModel = Field(default_factory=LinkCheckModel)
 
     redirects: dict[str, str] = Field(
@@ -555,7 +553,7 @@ class DocumenteerConfig:
         [sphinx] table is not set.
         """
         if self.conf.sphinx:
-            return self.conf.sphinx.intersphinx_cache
+            return self.conf.sphinx.intersphinx.cache
         return IntersphinxCacheModel()
 
     @property

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/src/documenteer/ext/autotypes/xrefs.py

@@ -36,8 +36,11 @@ resolution policy:
   ``repr()`` that happens to *parse* as Python is split into fragments
   instead of mangled, so the fragments of a documented class's own
   ``Annotated`` metadata (``Ge``, ``file``, ``ExecutionPhase.PENDING``)
-  degrade too. Project-local objects under wholly public module paths
-  keep warning: those are the ones that should be exported and
+  degrade too — as do the fragments of a *type alias's* own ``Annotated``
+  value (``PydanticUndefined``, ``json``), which surface on pages carrying
+  only a ``py:module`` context and are therefore recognized per module
+  rather than per class. Project-local objects under wholly public module
+  paths keep warning: those are the ones that should be exported and
   documented, so they stay visible.
 
 - Modules documented with ``automodapi::`` and ``:no-main-docstr:`` get a
@@ -244,10 +247,20 @@ def _project_typing_registry(
     return registry
 
 
+def _import_module(modname: str) -> types.ModuleType | None:
+    """Import ``modname``, or return None."""
+    try:
+        return importlib.import_module(modname)
+    except Exception:
+        return None
+
+
 def _import_from_module(modname: str, attrname: str) -> Any | None:
     """Import ``modname`` and return its ``attrname`` attribute, or None."""
+    module = _import_module(modname)
+    if module is None:
+        return None
     try:
-        module = importlib.import_module(modname)
         return getattr(module, attrname, None)
     except Exception:
         return None
@@ -1168,16 +1181,115 @@ def _annotated_metadata_fragments(
         if isinstance(value, str):
             fragments |= _source_metadata_names(value)
             continue
-        for metadata in _iter_annotated_metadata(value, set()):
-            for rendering in _render_metadata_object(metadata):
-                tree = _parse_expression(rendering)
-                if tree is not None:
-                    fragments |= _expression_names(tree)
+        fragments |= _runtime_metadata_fragments(value)
     result = frozenset(fragments)
     by_class[id(cls)] = result
     return result
 
 
+def _runtime_metadata_fragments(value: Any) -> set[str]:
+    """Collect the names Sphinx's rendering of *value*'s metadata emits.
+
+    Every ``Annotated`` form nested in *value* contributes the names of
+    both renderings its metadata objects can take
+    (:func:`_render_metadata_object`), for the renderings that parse as
+    Python — the ones Sphinx's annotation parser splits into fragments
+    rather than mangling whole (:func:`_is_mangled_target`).
+    """
+    fragments: set[str] = set()
+    for metadata in _iter_annotated_metadata(value, set()):
+        for rendering in _render_metadata_object(metadata):
+            tree = _parse_expression(rendering)
+            if tree is not None:
+                fragments |= _expression_names(tree)
+    return fragments
+
+
+def _module_alias_values(modname: str) -> list[Any]:
+    """Collect the alias values a module exposes publicly.
+
+    Both alias shapes a module can publish are read, since Sphinx renders
+    the metadata of either into the alias's own page: a :pep:`695`
+    ``type`` statement, whose ``TypeAliasType`` is unwrapped to the
+    (lazily evaluated) value it stands for, and an assignment-style
+    ``Annotated`` alias, which *is* its value
+    (:func:`~documenteer.ext.autotypes._shared._is_annotated_alias`).
+
+    Only public attributes count, and every probe is guarded: evaluating
+    a lazy alias value can raise (a ``type`` statement naming something
+    undefined), and reading an arbitrary module attribute can raise
+    anything at all (Pydantic's mock validators raise
+    ``PydanticUserError``).
+    """
+    module = _import_module(modname)
+    if module is None:
+        return []
+    try:
+        attrs = dict(vars(module))
+    except TypeError:
+        return []
+    values: list[Any] = []
+    for attr, value in attrs.items():
+        if attr.startswith("_"):
+            continue
+        if isinstance(value, TypeAliasType):
+            with contextlib.suppress(Exception):
+                values.append(value.__value__)
+        elif _is_annotated_alias(value):
+            values.append(value)
+    return values
+
+
+_alias_fragment_cache: dict[int, dict[str, frozenset[str]]] = {}
+
+
+def _alias_metadata_fragments(
+    modname: str, env: BuildEnvironment | None = None
+) -> frozenset[str]:
+    """Index the names a module's alias ``Annotated`` metadata synthesizes.
+
+    This is the module-scoped sibling of
+    :func:`_annotated_metadata_fragments`, and it exists because the same
+    fragments surface in a second place: a type alias's *own* page.
+    Sphinx renders the alias's value there, metadata and all, and unparses
+    the result into cross-references — so Safir's ``IvoaIsoDatetime``,
+    whose value carries a ``BeforeValidator`` and a ``PlainSerializer``,
+    emits a ``PydanticUndefined`` (the repr of a sentinel default) and a
+    ``json`` (the unquoted string value of ``when_used="json"``) target.
+    Those describe how a value is validated and serialized; neither names
+    anything that could be documented.
+
+    The class-scoped rung cannot cover them: an alias page carries no
+    ``py:class`` context at all, only the ``py:module`` of the module the
+    alias is documented from. That module — not the alias's defining
+    module — is therefore what this is indexed by, and it is the whole
+    guardrail: a name that no alias of *this* module renders keeps
+    warning, and a fragment of one module's alias does not degrade under
+    another module's context.
+
+    Like its class-scoped sibling the index resolves nothing, so it adds
+    no lookup surface: it is consulted only after every resolution rung,
+    and the class-scoped rung, have already failed. It is cached per
+    build environment and module, following
+    :func:`_annotated_metadata_fragments`.
+    """
+    key = id(env)
+    by_module = _alias_fragment_cache.get(key)
+    if by_module is None:
+        _alias_fragment_cache.clear()
+        by_module = {}
+        _alias_fragment_cache[key] = by_module
+    cached = by_module.get(modname)
+    if cached is not None:
+        return cached
+    fragments: set[str] = set()
+    for value in _module_alias_values(modname):
+        fragments |= _runtime_metadata_fragments(value)
+    result = frozenset(fragments)
+    by_module[modname] = result
+    return result
+
+
 def _missing_reference(  # noqa: C901, PLR0912
     app: Sphinx,
     env: BuildEnvironment,
@@ -1315,6 +1427,21 @@ def _missing_reference(  # noqa: C901, PLR0912
     if cls is not None and base in _annotated_metadata_fragments(cls, env):
         return contnode
 
+    # The same fragment family on a *type alias's* own page, where the
+    # reference carries no ``py:class`` context for the rung above to read
+    # — only the ``py:module`` of the module the alias is documented from.
+    # Safir's ``IvoaIsoDatetime`` is the case: its value's
+    # ``BeforeValidator``/``PlainSerializer`` metadata renders a
+    # ``PydanticUndefined`` sentinel repr and an unquoted ``json`` string
+    # value into the alias's rendered value, and Sphinx unparses both into
+    # targets. Unlinked literal, not a warning. Only names some alias of
+    # *this* module renders count, so names from elsewhere keep warning.
+    module_context = node.get("py:module")
+    if module_context and base in _alias_metadata_fragments(
+        module_context, env
+    ):
+        return contnode
+
     return None
 
 

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/src/documenteer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.5.0b2
+Version: 2.5.0b3
 Summary: Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.
 License-Expression: MIT
 Project-URL: Homepage, https://documenteer.lsst.io

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/src/documenteer.egg-info/SOURCES.txt

@@ -90,6 +90,7 @@ changelog.d/20260806_000002_jonathan_DM_55745_github_icon.md
 changelog.d/20260806_000003_jonathan_DM_55745_footer.md
 changelog.d/20260807_000000_jonathan_DM_55745_drop_rubin_docs_link.md
 changelog.d/20260812_000000_jonathan_DM_55690_sphinx9_gaps.md
+changelog.d/20260813_000000_jonathan_DM_55690_alias_metadata_fragments.md
 changelog.d/_template.md.jinja
 demo/ipynb-technote/.gitignore
 demo/ipynb-technote/Makefile
@@ -344,8 +345,12 @@ tests/roots/test-autotypes-alias/aliasroot/__init__.py
 tests/roots/test-autotypes-alias/aliasroot/documented/__init__.py
 tests/roots/test-autotypes-alias/aliasroot/documented/helpers.py
 tests/roots/test-autotypes-alias/aliasroot/external/__init__.py
+tests/roots/test-autotypes-annotated/aliases.rst
 tests/roots/test-autotypes-annotated/conf.py
 tests/roots/test-autotypes-annotated/index.rst
+tests/roots/test-autotypes-annotated/aliaspkg/__init__.py
+tests/roots/test-autotypes-annotated/aliaspkg/_types.py
+tests/roots/test-autotypes-annotated/aliaspkg/legacy.py
 tests/roots/test-autotypes-annotated/annotatedpkg/__init__.py
 tests/roots/test-autotypes-annotated/annotatedpkg/constrained.py
 tests/roots/test-autotypes-annotated/annotatedpkg/phased.py

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/src/documenteer.egg-info/scm_file_list.json

@@ -84,6 +84,7 @@
     "changelog.d/20260806_000003_jonathan_DM_55745_footer.md",
     "changelog.d/20260807_000000_jonathan_DM_55745_drop_rubin_docs_link.md",
     "changelog.d/20260812_000000_jonathan_DM_55690_sphinx9_gaps.md",
+    "changelog.d/20260813_000000_jonathan_DM_55690_alias_metadata_fragments.md",
     "changelog.d/_template.md.jinja",
     "demo/ipynb-technote/.gitignore",
     "demo/ipynb-technote/Makefile",
@@ -318,6 +319,10 @@
     "tests/roots/test-autotypes-alias/aliasroot/external/__init__.py",
     "tests/roots/test-autotypes-alias/conf.py",
     "tests/roots/test-autotypes-alias/index.rst",
+    "tests/roots/test-autotypes-annotated/aliases.rst",
+    "tests/roots/test-autotypes-annotated/aliaspkg/__init__.py",
+    "tests/roots/test-autotypes-annotated/aliaspkg/_types.py",
+    "tests/roots/test-autotypes-annotated/aliaspkg/legacy.py",
     "tests/roots/test-autotypes-annotated/annotatedpkg/__init__.py",
     "tests/roots/test-autotypes-annotated/annotatedpkg/constrained.py",
     "tests/roots/test-autotypes-annotated/annotatedpkg/phased.py",

documenteer-2.5.0b3/src/documenteer.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.5.0b3",
+  "distance": 0,
+  "node": "g4e40331d6a230a002395f7244919908082eeefb8",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-14"
+}

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/tests/ext/autotypes_test.py

@@ -20,6 +20,8 @@ from documenteer.ext.autotypes.documenters import (
 )
 from documenteer.ext.autotypes.xrefs import (
     _AMBIGUOUS,
+    _alias_fragment_cache,
+    _alias_metadata_fragments,
     _annotated_metadata_fragments,
     _candidate_names,
     _is_mangled_target,
@@ -434,6 +436,94 @@ def test_autotypes_annotated_metadata_negatives(app: SphinxTestApp) -> None:
     assert resolve("ExecutionPhase.PENDING", "SentryConfig") is None
 
 
+def _object_entry(html: str, object_id: str) -> str:
+    """Return the whole markup of one documented object.
+
+    An alias's value is rendered in its *body* rather than in its
+    signature line (the ``py:type`` directive's ``:canonical:`` option
+    becomes an "alias of" paragraph), so the slice runs to the end of the
+    definition rather than to the end of the signature.
+    """
+    start = html.index(f'id="{object_id}"')
+    return html[start : html.index("</dd>", start)]
+
+
+@pytest.mark.sphinx(
+    "html", testroot="autotypes-annotated", srcdir="autotypes-alias-metadata"
+)
+def test_autotypes_alias_metadata(app: SphinxTestApp, warning) -> None:
+    """Fragments of an alias's own Annotated metadata degrade to text."""
+    app.build()
+    assert "reference target not found" not in warning.getvalue()
+
+    html = (app.outdir / "aliases.html").read_text()
+
+    # The rendered alias values below are fully degraded, so the only
+    # anchor in each entry is its own ¶ headerlink.
+    def entry(name: str) -> str:
+        markup = _object_entry(html, f"aliaspkg.{name}")
+        assert markup.count("<a") == markup.count('<a class="headerlink"')
+        return markup
+
+    # The PEP 695 alias: ``PydanticUndefined`` is the repr of a dataclass
+    # metadata field's sentinel default, and ``json`` is another field's
+    # string value, stringified into the rendering without its quotes.
+    iso = entry("IsoDatetime")
+    assert ">PydanticUndefined<" in iso
+    assert ">json<" in iso
+
+    # The assignment-style alias, documented as data. Sphinx renders its
+    # whole value into the signature of the function it annotates — an
+    # assignment alias knows neither its name nor its module — so the same
+    # metadata fragments surface there, under the same module-only context.
+    assert 'id="aliaspkg.TrimmedName"' in html
+    register = entry("register")
+    assert ">PydanticUndefined<" in register
+    assert ">always<" in register
+
+
+@pytest.mark.sphinx(
+    "html",
+    testroot="autotypes-annotated",
+    srcdir="autotypes-alias-metadata-neg",
+)
+def test_autotypes_alias_metadata_negatives(app: SphinxTestApp) -> None:
+    """Names no alias rendering in the context module produces still warn."""
+    app.build()
+
+    def resolve(target: str, module: str) -> nodes.Element | None:
+        contnode = nodes.literal("", target)
+        node = addnodes.pending_xref(
+            "",
+            contnode,
+            refdomain="py",
+            reftype="class",
+            reftarget=target,
+            **{"py:module": module},
+        )
+        return _missing_reference(app, app.env, node, contnode)
+
+    # The fragments themselves degrade under the module the aliases are
+    # documented from — from the PEP 695 alias and, for ``always``, from
+    # the assignment-style one.
+    assert resolve("PydanticUndefined", "aliaspkg") is not None
+    assert resolve("json", "aliaspkg") is not None
+    assert resolve("always", "aliaspkg") is not None
+
+    # A typo of a fragment is in no alias's rendering, so it still warns.
+    assert resolve("PydanticUndefinde", "aliaspkg") is None
+    assert resolve("jsonl", "aliaspkg") is None
+
+    # The index is per module: ``aliaspkg.legacy``'s own alias renders
+    # neither the sentinel default nor the ``always`` string value, so a
+    # fragment of the package's aliases does not degrade under it.
+    assert resolve("PydanticUndefined", "aliaspkg.legacy") is None
+    assert resolve("always", "aliaspkg.legacy") is None
+
+    # A module with no ``Annotated`` alias at all degrades nothing.
+    assert resolve("PydanticUndefined", "annotatedpkg") is None
+
+
 @pytest.mark.sphinx("html", testroot="autotypes-typehints")
 def test_autotypes_callable_singleton(app: SphinxTestApp, warning) -> None:
     """A module-level callable singleton survives the build."""
@@ -1176,6 +1266,154 @@ def test_annotated_metadata_fragments_misses() -> None:
     )
 
 
+def _iso_normalize(value: str) -> str:
+    """Stand in for Safir's ``normalize_isodatetime`` validator function.
+
+    A module-level function is what the rendering under test needs: Sphinx
+    writes a dataclass metadata field's value with
+    ``stringify_annotation``, which renders a function as its dotted
+    ``module.qualname``. A nested function's qualname carries
+    ``<locals>``, whose angle brackets would make the whole rendering
+    unparseable and leave no fragments at all.
+    """
+    return value
+
+
+def _iso_render(value: object) -> str:
+    """Stand in for Safir's ``isodatetime`` serializer function."""
+    return str(value)
+
+
+def _validator_alias_value() -> object:
+    """Build the ``Annotated`` form of Safir's ``IvoaIsoDatetime``.
+
+    ``BeforeValidator.json_schema_input_type`` defaults to the
+    ``PydanticUndefined`` sentinel and ``PlainSerializer.when_used`` is a
+    string, so Sphinx's field-by-field rendering of these two dataclasses
+    is what emits the ``PydanticUndefined`` and ``json`` targets that
+    issue #385 reports as nitpick warnings.
+    """
+    from datetime import datetime  # noqa: PLC0415
+    from typing import Annotated  # noqa: PLC0415
+
+    from pydantic import BeforeValidator, PlainSerializer  # noqa: PLC0415
+
+    return Annotated[
+        datetime,
+        BeforeValidator(_iso_normalize),
+        PlainSerializer(_iso_render, return_type=str, when_used="json"),
+    ]
+
+
+@pytest.fixture
+def clear_alias_fragment_cache():
+    """Isolate the module-scoped alias fragment index's cache.
+
+    The index is keyed by ``id(env)`` and then by module name, and these
+    unit tests pass no environment at all — so without this they would
+    all share the ``id(None)`` bucket and could be served another test's
+    synthetic module under the same name.
+    """
+    _alias_fragment_cache.clear()
+    yield
+    _alias_fragment_cache.clear()
+
+
+def test_alias_metadata_fragments_type_alias(
+    monkeypatch, clear_alias_fragment_cache
+) -> None:
+    """A PEP 695 alias's own ``Annotated`` metadata supplies fragments."""
+    from typing import TypeAliasType  # noqa: PLC0415
+
+    _install_modules(
+        monkeypatch,
+        {
+            "aliasfragprobe": {
+                "IsoDatetime": TypeAliasType(
+                    "IsoDatetime", _validator_alias_value()
+                )
+            }
+        },
+    )
+
+    fragments = _alias_metadata_fragments("aliasfragprobe")
+
+    # The sentinel-object default and the unquoted string field value.
+    assert {"PydanticUndefined", "json"} <= fragments
+
+    # The annotated type is not metadata, so it keeps following the
+    # ordinary resolution ladder rather than degrading here.
+    assert "datetime.datetime" not in fragments
+
+
+def test_alias_metadata_fragments_assignment_alias(
+    monkeypatch, clear_alias_fragment_cache
+) -> None:
+    """An assignment-style ``Annotated`` module alias contributes too."""
+    from typing import Annotated  # noqa: PLC0415
+
+    from pydantic import BeforeValidator  # noqa: PLC0415
+
+    _install_modules(
+        monkeypatch,
+        {
+            "aliasfragprobe": {
+                "TrimmedName": Annotated[str, BeforeValidator(_iso_normalize)]
+            }
+        },
+    )
+
+    fragments = _alias_metadata_fragments("aliasfragprobe")
+
+    assert "PydanticUndefined" in fragments
+    assert "aliasfragprobe.other" not in fragments
+
+    # ``str`` is the annotated type here, not a metadata rendering.
+    assert "str" not in fragments
+
+
+def test_alias_metadata_fragments_misses(
+    monkeypatch, clear_alias_fragment_cache
+) -> None:
+    """Names no alias rendering in the module produces are not fragments."""
+    from typing import Annotated, TypeAliasType  # noqa: PLC0415
+
+    from pydantic import PlainSerializer  # noqa: PLC0415
+
+    _install_modules(
+        monkeypatch,
+        {
+            "aliasfragprobe": {
+                "IsoDatetime": TypeAliasType(
+                    "IsoDatetime", _validator_alias_value()
+                ),
+                "_Hidden": Annotated[
+                    str,
+                    PlainSerializer(_iso_render, when_used="unless_none"),
+                ],
+                "MAX_LENGTH": 64,
+            },
+            "aliasfragprobe.other": {"Loader": type("Loader", (), {})},
+        },
+    )
+
+    fragments = _alias_metadata_fragments("aliasfragprobe")
+
+    # A typo of a fragment, and a real but unrelated class, keep warning.
+    assert "jsonl" not in fragments
+    assert "ModuleAnalyzer" not in fragments
+
+    # Only public attributes are scanned, so a private alias's own
+    # fragments are not admitted.
+    assert "unless_none" not in fragments
+
+    # The index is per module: a sibling module with no ``Annotated``
+    # alias of its own produces nothing, and neither does a module that
+    # cannot be imported at all.
+    assert _alias_metadata_fragments("aliasfragprobe.other") == frozenset()
+    assert _alias_metadata_fragments("nosuchaliasprobe") == frozenset()
+
+
 def test_strip_bogus_typing_prefix() -> None:
     # PEP 695 scoped type parameters that sphinx-autodoc-typehints
     # qualified with a bogus ``typing.`` prefix.

{documenteer-2.5.0b2 → documenteer-2.5.0b3}/tests/ext/intersphinxcache_test.py

@@ -945,7 +945,7 @@ def test_guide_preset_registers_extension(
     monkeypatch: Any,
 ) -> None:
     """The guide preset registers the intersphinxcache extension and wires
-    the [sphinx.intersphinx_cache] settings through to its config values.
+    the [sphinx.intersphinx.cache] settings through to its config values.
     """
     monkeypatch.delenv("OOK_TOKEN", raising=False)
 

documenteer-2.5.0b3/tests/roots/test-autotypes-annotated/aliases.rst

@@ -0,0 +1,17 @@
+Alias-metadata fragments
+========================
+
+.. automodule:: aliaspkg
+
+Both alias spellings, documented from the package that re-exports them,
+plus a function annotated with the assignment-style one. Sphinx renders
+each alias's whole ``Annotated`` value — validator and serializer metadata
+included — into the alias's own page and into that signature, where a
+reference carries no ``py:class`` context at all, only this module's
+``py:module``.
+
+.. autotype:: aliaspkg.IsoDatetime
+
+.. autodata:: aliaspkg.TrimmedName
+
+.. autofunction:: aliaspkg.register

documenteer-2.5.0b3/tests/roots/test-autotypes-annotated/aliaspkg/__init__.py

@@ -0,0 +1,13 @@
+"""A package documenting the aliases it re-exports from a private module.
+
+This mirrors ``safir.pydantic``, which publishes ``IvoaIsoDatetime`` from
+``safir.pydantic._types``: an alias page's ``py:module`` context is the
+package the alias is documented *from*, never the module it was written
+in, which is the module the fragment index has to be keyed by.
+"""
+
+from __future__ import annotations
+
+from ._types import IsoDatetime, TrimmedName, register
+
+__all__ = ["IsoDatetime", "TrimmedName", "register"]