Fix two broken links that -W cannot see (#81)

Neither defect is a resolved reference, so a warnings-as-errors build
reported nothing while both shipped 404s.

`sphinx-gp-llms` advertised a Markdown twin in the page footer for every
page, while twins were written only for real source documents, so
`genindex`, `py-modindex` and `search` each linked a file that was never
created. One predicate now owns the three conditions a twin requires --
the page is in `found_docs`, it does not match `llms_excludes`, and its
source exists -- and both the writer and the page-context handler call
it, so the link and the writer cannot drift apart again.

`gp-sphinx` deletes `_static/tabs.js` after each HTML build, working
around a `sphinx-inline-tabs` script that conflicts with SPA navigation,
but nothing dropped the `<script>` tag the extension registers; every
page then requested an asset the build had just removed. The tag is now
dropped alongside the file. Tab switching is unaffected, being driven by
CSS, and cross-group sync remains the standing cost of the workaround
rather than a regression here.

Smartquotes mangling literal JSON in an argument description was
reported alongside these and is deliberately unchanged: descriptions are
already parsed as inline markup, so a literal reaches docutils intact,
and only generated boilerplate arrives unprotected.

Author: tony

CHANGES

@@ -20,6 +20,24 @@ $ uv add gp-sphinx --prerelease allow
 
 ### Fixes
 
+#### `sphinx-gp-llms`: A Markdown twin link only where a twin exists
+
+The page footer advertised a `.md` sibling on every page, while twins were
+written only for real source documents, so `genindex`, `py-modindex` and
+`search` each linked a file that was never created. The link is rendered from
+the template rather than resolved as a reference, so nothing reported it, not
+even under `-W`. The footer now offers the link only for a page that has a
+twin -- covering an excluded page and a page whose source is absent, as well
+as a generated one. (#81)
+
+#### `gp-sphinx`: Pages no longer request the `tabs.js` the build removes
+
+`sphinx-inline-tabs` ships a `tabs.js` that conflicts with SPA navigation, and
+gp-sphinx deletes it after each HTML build. Nothing dropped the `<script>` tag
+the extension registers, so every page requested an asset that was not there.
+The tag is now dropped alongside the file. Tab switching is unaffected, being
+driven by CSS. (#81)
+
 #### `sphinx-autodoc-fastmcp`: An axis cannot claim a component's id namespace
 
 `fastmcp-tool-summary` anchors its sections on `fastmcp-<axis>-<term>`,

docs/configuration.md

@@ -92,6 +92,7 @@ browser helpers, autodoc filter, and lexer aliases into the Sphinx app:
 | `app.add_js_file("js/spa-nav.js", loading_method="defer")` | Registers the bundled SPA navigation script from `sphinx-gp-theme` |
 | `app.connect("html-page-context", _inject_copybutton_bridge)` | Adds copybutton prompt settings to the page context so copied examples stay prompt-aware after SPA navigation |
 | `app.connect("html-page-context", _inject_fowt_prevention)` | Injects the early theme script that prevents a flash of the wrong theme before Furo initializes |
+| `app.connect("html-page-context", _drop_tabs_js_reference)` | Drops the `_static/tabs.js` `<script>` tag, so pages do not request the file `remove_tabs_js` deletes |
 | `app.connect("build-finished", remove_tabs_js)` | Removes `_static/tabs.js` after HTML builds as a `sphinx-inline-tabs` workaround |
 | `app.connect("autodoc-skip-member", skip_machinery_members, priority=900)` | Hides the {py:data}`gp_sphinx.config.MACHINERY_MEMBERS` names that {py:class}`abc.ABCMeta`, {py:class}`typing.Protocol`, and {py:class}`typing.NamedTuple` write into a class |
 | `app.add_lexer("myst", MystLexer)` | Registers the MyST lexer alias used by Markdown examples |

packages/gp-sphinx/src/gp_sphinx/config.py

@@ -32,6 +32,7 @@
 import logging
 import os.path
 import pathlib
+import posixpath
 import sys
 import typing as t
 
@@ -628,6 +629,10 @@ def merge_sphinx_config(
     return conf
 
 
+#: Asset ``sphinx-inline-tabs`` ships that conflicts with SPA navigation.
+_TABS_JS_NAME = "tabs.js"
+
+
 def remove_tabs_js(app: Sphinx, exc: Exception | None) -> None:
     """Remove ``tabs.js`` from ``_static`` after build.
 
@@ -642,11 +647,76 @@ def remove_tabs_js(app: Sphinx, exc: Exception | None) -> None:
         Build exception, if any.
     """
     if app.builder.format == "html" and not exc:
-        tabs_js = pathlib.Path(app.builder.outdir) / "_static" / "tabs.js"
+        tabs_js = pathlib.Path(app.builder.outdir) / "_static" / _TABS_JS_NAME
         with contextlib.suppress(FileNotFoundError):
             tabs_js.unlink()
 
 
+def _is_tabs_js(asset: object) -> bool:
+    """Return whether *asset* is the ``tabs.js`` :func:`remove_tabs_js` deletes.
+
+    Sphinx models a script as ``_JavaScript``, whose ``__str__`` renders the
+    whole ``<script>`` tag rather than the path, so the filename must be read
+    from the attribute. Compare the base name: ``design-tabs.js``, which
+    ``sphinx-design`` ships and which is copied normally, ends with the same
+    text.
+
+    Parameters
+    ----------
+    asset : object
+        Entry from the page context's ``script_files``.
+
+    Returns
+    -------
+    bool
+        ``True`` when the entry refers to ``tabs.js``.
+
+    Examples
+    --------
+    >>> _is_tabs_js("_static/tabs.js")
+    True
+    >>> _is_tabs_js("_static/design-tabs.js")
+    False
+    """
+    filename = getattr(asset, "filename", asset)
+    return posixpath.basename(str(filename)) == _TABS_JS_NAME
+
+
+def _drop_tabs_js_reference(
+    app: Sphinx,
+    pagename: str,
+    templatename: str,
+    context: dict[str, t.Any],
+    doctree: object,
+) -> None:
+    """Stop pages referencing the ``tabs.js`` that :func:`remove_tabs_js` deletes.
+
+    ``sphinx-inline-tabs`` registers ``tabs.js`` in its ``setup()``, so every
+    page renders a ``<script>`` tag for it. Deleting the built file without
+    dropping the tag leaves every page requesting an asset that is not there.
+    Sphinx supports rewriting ``script_files`` from this event.
+
+    Parameters
+    ----------
+    app : Sphinx
+        The Sphinx application object.
+    pagename : str
+        Name of the page being rendered.
+    templatename : str
+        Template about to be rendered.
+    context : dict
+        Jinja2 context for the page.
+    doctree : object
+        Resolved doctree, or a falsy value for a generated page.
+    """
+    del app, pagename, templatename, doctree
+
+    script_files = context.get("script_files")
+    if not script_files:
+        return
+    context["script_files"] = [js for js in script_files if not _is_tabs_js(js)]
+
+
 def _inject_copybutton_bridge(
     app: Sphinx,
     pagename: str,
@@ -875,6 +945,7 @@ def setup(app: Sphinx) -> None:
     app.add_js_file("js/spa-nav.js", loading_method="defer")
     app.connect("html-page-context", _inject_copybutton_bridge)
     app.connect("html-page-context", _inject_fowt_prevention)
+    app.connect("html-page-context", _drop_tabs_js_reference)
     app.connect("build-finished", remove_tabs_js)
     app.connect(
         "autodoc-skip-member",

packages/sphinx-gp-llms/src/sphinx_gp_llms/__init__.py

@@ -209,7 +209,10 @@ def _inject_llms_context(
         return
 
     if app.config.llms_generate_md_twins:
-        context["llms_md_url"] = pagename + ".md"
+        from sphinx_gp_llms._md_twins import has_md_twin
+
+        if has_md_twin(app, pagename):
+            context["llms_md_url"] = pagename + ".md"
     if app.config.llms_generate_txt:
         context["llms_txt_url"] = app.config.llms_txt_filename
     if app.config.llms_generate_full:

packages/sphinx-gp-llms/src/sphinx_gp_llms/_md_twins.py

@@ -27,6 +27,41 @@
 logger = getLogger(__name__)
 
 
+def has_md_twin(app: Sphinx, docname: str) -> bool:
+    """Return whether :func:`write_md_twins` writes a twin for *docname*.
+
+    The footer link and the twin writer must agree: a page linked to a
+    ``.md`` sibling that was never written is a 404 the build cannot see,
+    because the link is rendered from the template rather than resolved as
+    a reference.
+
+    Parameters
+    ----------
+    app : Sphinx
+        Sphinx application instance.
+    docname : str
+        Document name, as passed to ``html-page-context``.
+
+    Returns
+    -------
+    bool
+        ``True`` when a twin exists for *docname*.
+
+    Examples
+    --------
+    >>> from sphinx_gp_llms._md_twins import has_md_twin
+    >>> callable(has_md_twin)
+    True
+    """
+    if docname not in app.env.found_docs:
+        return False
+    if _is_excluded(
+        app.builder.get_target_uri(docname), list(app.config.llms_excludes)
+    ):
+        return False
+    return pathlib.Path(app.env.doc2path(docname)).exists()
+
+
 def write_md_twins(app: Sphinx) -> None:
     """Copy source files as ``.md`` siblings in the build output directory.
 
@@ -41,19 +76,14 @@ def write_md_twins(app: Sphinx) -> None:
     >>> callable(write_md_twins)
     True
     """
-    excludes: list[str] = list(app.config.llms_excludes)
     outdir = pathlib.Path(app.outdir)
     count = 0
 
     for docname in sorted(app.env.found_docs):
-        uri = app.builder.get_target_uri(docname)
-        if _is_excluded(uri, excludes):
+        if not has_md_twin(app, docname):
             continue
 
         source_path = pathlib.Path(app.env.doc2path(docname))
-        if not source_path.exists():
-            continue
-
         target = outdir / (docname + ".md")
         target.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(source_path, target)

tests/ext/llms/test_md_twins.py

@@ -50,3 +50,76 @@ def test_md_twin_content_matches_source(
         encoding="utf-8",
     )
     assert "Get started with the project quickly." in md_content
+
+
+_GENERATED_PAGES = ["genindex", "py-modindex", "search"]
+
+
+@pytest.mark.parametrize("pagename", _GENERATED_PAGES)
+def test_generated_pages_advertise_no_md_twin(
+    pagename: str,
+    llms_build: LlmsBuildResult,
+) -> None:
+    """A page Sphinx generates has no source, so it must not link a twin."""
+    from sphinx_gp_llms._md_twins import has_md_twin
+
+    app = llms_build.result.app
+    assert not has_md_twin(app, pagename)
+    assert not (llms_build.result.outdir / f"{pagename}.md").exists()
+
+
+def test_the_twin_link_and_the_twin_writer_agree(
+    llms_build: LlmsBuildResult,
+) -> None:
+    """Every page advertising a twin has one, and vice versa.
+
+    The footer link is rendered from the template rather than resolved as a
+    reference, so Sphinx never reports a twin link that points at nothing --
+    not even under ``-W``. This invariant is what catches it instead.
+    """
+    from sphinx_gp_llms._md_twins import has_md_twin
+
+    app = llms_build.result.app
+    outdir = llms_build.result.outdir
+    candidates = sorted(app.env.found_docs) + _GENERATED_PAGES
+
+    advertised = {name for name in candidates if has_md_twin(app, name)}
+    written = {name for name in candidates if (outdir / f"{name}.md").exists()}
+
+    assert advertised == written
+
+
+class TwinContextCase(t.NamedTuple):
+    """Whether a pagename should be offered a Markdown twin link."""
+
+    test_id: str
+    pagename: str
+    expects_link: bool
+
+
+_CONTEXT_CASES: list[TwinContextCase] = [
+    TwinContextCase(test_id="real-page", pagename="index", expects_link=True),
+    TwinContextCase(test_id="genindex", pagename="genindex", expects_link=False),
+    TwinContextCase(test_id="modindex", pagename="py-modindex", expects_link=False),
+    TwinContextCase(test_id="search", pagename="search", expects_link=False),
+]
+
+
+@pytest.mark.parametrize(
+    list(TwinContextCase._fields),
+    _CONTEXT_CASES,
+    ids=[c.test_id for c in _CONTEXT_CASES],
+)
+def test_only_a_page_with_a_twin_is_offered_the_link(
+    test_id: str,
+    pagename: str,
+    expects_link: bool,
+    llms_build: LlmsBuildResult,
+) -> None:
+    """The footer variable is set only when the twin was written."""
+    from sphinx_gp_llms import _inject_llms_context
+
+    context: dict[str, t.Any] = {}
+    _inject_llms_context(llms_build.result.app, pagename, "page.html", context, None)
+
+    assert ("llms_md_url" in context) is expects_link