Sphinx LLM (experimental, maintenance-gated)#

_sphinx_llm is the Scikit-Plots subsystem for static machine-consumable Sphinx artifacts. It combines a pinned NVIDIA-derived baseline with Scikit-Plots compatibility, semantic-adapter, curation and artifact layers.

Warning

This subsystem is under an explicit maintenance campaign and is not the default documentation path in the current Scikit-Plots conf.py. Treat it as experimental until its maintained compatibility gates are complete. Do not infer release readiness merely because setup(app) exists.

Intended output model#

The current design favors targeted retrieval:

HTML page
   |-- discover -> canonical Markdown for that page
   `-- discover -> applicable llms.txt

rather than requiring every consumer to load one giant full-corpus file. llms-full.txt remains optional and is controlled by an explicit size/policy surface.

Basic registration#

For an experimental build that has passed the subsystem’s local maintenance gates:

extensions += [
    "scikitplot._externals._sphinx_ext._sphinx_llm",
]

llms_txt_enabled = True
llms_txt_discovery_links = True
llms_txt_unknown_node_policy = "warn"
llms_txt_full_build = False
llms_txt_html_fallback = False

The extension injects page-relative discovery links only for HTML/dirhtml builders.

Semantic directives#

Two author-facing directives are currently registered:

llms-ignore

Suppresses a subtree from canonical machine Markdown while leaving normal human output transparent.

docref

Participates in the vendored/compatibility document-reference and summary workflow.

Configuration groups#

The configuration surface is intentionally broader than a single boolean. It includes:

  • core enablement, description and suffix routing;

  • include/exclude/ordering and section-curation policies;

  • unknown-node behavior and optional HTML fallback;

  • llms-full byte/character/line/document size limits and size policy;

  • discovery-link publication;

  • optional page-summary provider/model/endpoint/cache settings.

When remote summary generation is used, API credentials are read from the configured environment-variable name. The implementation includes safeguards against sending an API key to a non-loopback insecure endpoint unless the insecure-auth policy is explicitly enabled.

Coexistence with AI Assistant#

Sphinx AI Assistant also has an existing Markdown/llms.txt artifact pipeline. Until the repository defines one explicit coexistence or migration contract, do not enable both default writers and rely on event order to decide which llms.txt survives. Select one artifact owner or disable the overlapping output in one extension.