Add llms.txt support to documentation

[OptimalNothing90]

PR: Add llms.txt support to EMHASS documentation

Summary

This PR adds llms.txt support to the EMHASS documentation, enabling LLMs and AI coding assistants to efficiently consume the documentation at inference time.

Many EMHASS users already rely on AI tools (ChatGPT, Claude, Cursor, Copilot) to help configure and troubleshoot their setups. The llms.txt standard provides a structured, token-efficient way for these tools to access the full EMHASS documentation — resulting in better answers about configuration parameters, optimization modes, thermal models, and forecasting options.

What is llms.txt?

The llms.txt standard is a proposed convention (similar to robots.txt for search engines) that provides LLM-friendly content. It generates:

• /llms.txt — A summary/sitemap of all documentation pages in Markdown
• /llms-full.txt — The entire documentation concatenated into a single Markdown file
• /*.html.md — Individual Markdown versions of each HTML page

This is already adopted by projects like Anthropic, Vercel, Stripe, Cloudflare, and many others. Read the Docs natively supports serving these files.

Changes

1. docs/conf.py

Added sphinx_llm.txt to the Sphinx extensions list:

extensions = ["sphinx.ext.autodoc", "myst_parser", "sphinx_design", "sphinx_llm.txt"]

2. pyproject.toml

Added sphinx-llm to the docs optional dependencies:

docs = ["sphinx", "pydata-sphinx-theme", "sphinx-design", "myst-parser", "sphinx-llm"]

3. No other changes required

• The extension auto-generates llms.txt, llms-full.txt, and per-page .html.md files during the normal Sphinx build
• Read the Docs already supports serving llms.txt from the project root — no .readthedocs.yaml changes needed
• Zero maintenance overhead: the files regenerate on every docs build

How users benefit

After this change, users and AI tools can access:

URL	Content
https://emhass.readthedocs.io/llms.txt	Documentation sitemap for LLMs
https://emhass.readthedocs.io/llms-full.txt	Full documentation in one file
https://emhass.readthedocs.io/en/latest/config.html.md	Markdown version of any page

Practical use cases

• Cursor / Copilot / Claude Code: Add https://emhass.readthedocs.io/llms-full.txt as context via @Docs → better code suggestions for EMHASS automations
• ChatGPT / Claude: Paste the llms-full.txt URL for accurate configuration help
• MCP / Agents: AI agents can programmatically fetch structured EMHASS docs

Testing

The extension works alongside the existing myst_parser setup (which already parses Markdown source files). Verified that:

• sphinx-llm is compatible with pydata-sphinx-theme
• sphinx-llm is compatible with myst_parser and sphinx_design
• No changes to existing HTML output
• Generated files follow the llms.txt specification

Related

• llms.txt specification
• Read the Docs llms.txt support
• sphinx-llm on PyPI

Summary by Sourcery

Add llms.txt support to the Sphinx documentation build so that EMHASS docs are more easily consumed by LLMs and AI assistants.

Build:

• Extend Sphinx configuration to load the sphinx_llm.txt extension for generating llms.txt outputs.
• Add sphinx-llm to the documentation optional dependencies in pyproject.toml.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

This PR enables llms.txt support for the EMHASS documentation by adding the sphinx-llm extension to the Sphinx configuration and including its package in the docs optional dependencies, so that Read the Docs can automatically generate and serve LLM-friendly documentation artifacts.

Sequence diagram for AI tool accessing llms.txt resources

sequenceDiagram
    actor DevUser
    participant AITool
    participant Internet
    participant ReadTheDocs
    participant DocsArtifacts as Docs_artifacts

    DevUser->>AITool: Configure docs_source_url
    AITool->>Internet: Resolve emhass_readthedocs_url
    Internet->>ReadTheDocs: DNS_and_routing

    AITool->>ReadTheDocs: GET llms_txt
    ReadTheDocs->>DocsArtifacts: Read llms_txt
    DocsArtifacts-->>ReadTheDocs: llms_txt_content
    ReadTheDocs-->>AITool: 200 llms_txt_content

    AITool->>ReadTheDocs: GET llms_full_txt
    ReadTheDocs->>DocsArtifacts: Read llms_full_txt
    DocsArtifacts-->>ReadTheDocs: llms_full_txt_content
    ReadTheDocs-->>AITool: 200 llms_full_txt_content

    AITool->>DevUser: Provide_context_aware_suggestions

Loading

File-Level Changes

Change	Details	Files
Enable sphinx-llm extension in the Sphinx docs build so llms.txt artifacts are generated.	Extend the Sphinx extensions list to include the sphinx-llm plugin alongside existing autodoc, myst_parser, and sphinx_design. Rely on the plugin’s default behavior to generate llms.txt, llms-full.txt, and per-page .html.md files during normal builds without additional configuration.	docs/conf.py
Ensure sphinx-llm is installed in the docs build environment.	Add sphinx-llm to the docs extras group so it is installed when building documentation via optional dependencies.	pyproject.toml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• In docs/conf.py the Sphinx extension should likely be referenced as "sphinx_llm" (module name) rather than "sphinx_llm.txt", otherwise Sphinx may fail to load the extension.
• Consider formatting the extensions list over multiple lines now that it has grown, to keep it readable and easier to modify in future.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `docs/conf.py` the Sphinx extension should likely be referenced as `"sphinx_llm"` (module name) rather than `"sphinx_llm.txt"`, otherwise Sphinx may fail to load the extension.
- Consider formatting the `extensions` list over multiple lines now that it has grown, to keep it readable and easier to modify in future.

## Individual Comments

### Comment 1
<location path="docs/conf.py" line_range="36" />
<code_context>
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "myst_parser", "sphinx_design"]
+extensions = ["sphinx.ext.autodoc", "myst_parser", "sphinx_design", "sphinx_llm.txt"]

 myst_enable_extensions = [
</code_context>
<issue_to_address>
**issue (bug_risk):** The extension name `"sphinx_llm.txt"` looks like a potential typo or misconfiguration.

Sphinx expects extension entries to be importable module paths (e.g. `"sphinx_llm"`), not filenames. Using `.txt` here is likely to break the build because Sphinx won’t be able to import it. If you’re trying to enable the `sphinx-llm` package from `pyproject.toml`, this should probably be `"sphinx_llm"` (or the actual module name) instead of `"sphinx_llm.txt"`.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.91%. Comparing base (56a5e5f) to head (d0df1ba).
⚠️ Report is 5 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #792   +/-   ##
=======================================
  Coverage   81.91%   81.91%           
=======================================
  Files          10       10           
  Lines        5816     5816           
=======================================
  Hits         4764     4764           
  Misses       1052     1052           

☔ 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.