Add sphinx-gp-llms: LLM-friendly documentation outputs

[tony]

Summary

• Add new workspace package sphinx-gp-llms that generates four LLM-friendly output formats during the standard HTML Sphinx build
• Add llms.txt — structured Markdown index following the llmstxt.org spec (Jeremy Howard, Answer.AI), with H1 project name, blockquote summary, and H2 sections grouped by toctree captions
• Add llms-full.txt — concatenated full-content Markdown of all documentation pages, following the community convention adopted by Anthropic, Cloudflare, Mintlify, and GitBook
• Add docs.json — agent-oriented manifest with agentEntrypoints, per-page markdownUrl, and heading outlines, following the Lakebed/Ping convention
• Add per-page .md twins — source file copies alongside HTML output, following the Cloudflare "Markdown for Agents" convention
• Update the footer's Machine-readable line to link all formats: Markdown, raw source, docs.json, llms.txt, llms-full.txt
• Fix footer link injection to respect per-generate config flags — disabling an output no longer renders a broken link
• Fix footer template guard so LLM links render independently of source_repository
• Fix env.titles access to skip titleless pages instead of crashing

Design decisions

• Hook-based, not a custom Builder: Uses build-finished to generate files alongside the HTML build, matching the sphinx-gp-sitemap pattern. No separate build invocation needed — every sphinx-build automatically produces LLM outputs.
• Toctree captions as llms.txt sections: MyST's {toctree} :caption: option maps directly to the H2 sections in the llms.txt format, so existing toctree structure translates without new configuration.
• Silent no-op when site_url is unset: Projects without docs_url configured skip LLM output at INFO level, matching sitemap behavior. No broken builds.
• Footer links are context-injected and flag-gated: The html-page-context hook injects link URLs only when the extension is loaded and the corresponding llms_generate_* flag is True. The footer also renders LLM links independently of source_repository, falling back to an elif branch when the source-path section is unavailable.
• Defensive title access: Generators use env.titles.get(docname) and skip pages without titles (_llms_txt.py, _docs_json.py) or fall back to the docname (_llms_full_txt.py).

Verification

Verify all output files are generated:

$ ls docs/_build/html/llms.txt docs/_build/html/llms-full.txt docs/_build/html/docs.json

Verify per-page .md twins exist:

$ ls docs/_build/html/index.md docs/_build/html/configuration.md

Verify footer links render:

$ grep -c "llms.txt" docs/_build/html/configuration/index.html

Test plan

• uv run ruff check . — no lint issues
• uv run mypy — no type errors
• uv run pytest tests/ packages/ --reruns 0 — all tests pass
• just build-docs — docs build successfully with all LLM outputs
• llms.txt has correct H1/blockquote/H2 structure with page links
• llms-full.txt concatenates all page content with headers and separators
• docs.json has valid schema with agentEntrypoints and page entries
• .md twins exist alongside HTML for every content page
• Footer shows "Machine-readable: Markdown, raw source, docs.json, llms.txt, llms-full.txt" with working links
• Disabling a generate flag removes its footer link
• LLM links render even without source_repository configured
• Titleless pages don't crash the build

[codecov-commenter]

Codecov Report

❌ Patch coverage is 94.39024% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.87%. Comparing base (23bd389) to head (c569960).

Files with missing lines	Patch %	Lines
...ages/sphinx-gp-llms/src/sphinx_gp_llms/__init__.py	90.47%	6 Missing ⚠️
...es/sphinx-gp-llms/src/sphinx_gp_llms/_docs_json.py	95.40%	4 Missing ⚠️
scripts/ci/package_tools.py	20.00%	4 Missing ⚠️
...phinx-gp-llms/src/sphinx_gp_llms/_llms_full_txt.py	90.62%	3 Missing ⚠️
.../sphinx-gp-llms/src/sphinx_gp_llms/_description.py	92.59%	2 Missing ⚠️
...ges/sphinx-gp-llms/src/sphinx_gp_llms/_llms_txt.py	95.23%	2 Missing ⚠️
...ges/sphinx-gp-llms/src/sphinx_gp_llms/_md_twins.py	91.66%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #47      +/-   ##
==========================================
+ Coverage   91.82%   91.87%   +0.05%     
==========================================
  Files         220      233      +13     
  Lines       17776    18186     +410     
==========================================
+ Hits        16322    16709     +387     
- Misses       1454     1477      +23     

☔ 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

No issues found. Checked for bugs and CLAUDE.md compliance.

Notable observations below threshold (scored 75/100 — edge cases, not blocking):

• _inject_llms_context injects all link URLs unconditionally without checking llms_generate_* flags, so disabling an output (e.g. llms_generate_json = False) still renders its footer link (404). The sibling _write_llm_outputs does check each flag.
• The outer {%- if theme_source_repository and page_source_suffix -%} guard in page.html wraps the LLM links too, hiding them when source_repository is unset even though they don't depend on it.
• app.env.titles[docname] in _llms_txt.py, _llms_full_txt.py, _docs_json.py uses dict subscript — pages without a section heading would KeyError.

🤖 Generated with Claude Code

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