Use the package summary as the default llms.txt description by MaxFreedomPollard · Pull Request #198 · NVIDIA/sphinx-llm

MaxFreedomPollard · 2026-10-22T21:58:44Z

When llms_txt_description is not set, get_project_description() looks up the installed package named by project and reads its Description metadata field. That field holds the long description, which is usually the whole README. The description from pyproject.toml is stored in the Summary field.

During a Sphinx build this lookup returns the README on every supported Python version. On Python 3.10+, importlib.metadata exposes the metadata body as Description. On Python 3.9, Sphinx loads the importlib_metadata backport, which does the same. Any project whose project value is the name of an installed package therefore gets its entire README, including badges and headings, in the blockquote of the root llms.txt and of every nested llms.txt. The README documents the default as the project description from pyproject.toml.

Reproduction (Docutils is installed with Sphinx):

# conf.py
project = "docutils"
extensions = ["sphinx_llm.txt"]

With one short index.rst, sphinx-build -b html writes a 419-line llms.txt with a 412-line blockquote containing the Docutils 0.22.4 README. With this change, the blockquote is the single line > Docutils -- Python Documentation Utilities.

Changes:

Read Summary instead of Description. Packages without a summary still fall back to html_title.
Add a regression test that installs a temporary .dist-info with a README body, both with and without a summary.
Add a changelog entry.

Testing:

The new test fails on main in both cases, because the README is returned. It passes with the change on Python 3.14 with Sphinx 9.1, and on Python 3.9 with the lowest direct dependency versions (Sphinx 5.1, Docutils 0.15).
Full suite on Python 3.14 with Sphinx 9.1: 505 passed (503 on main, plus the two new cases).
ruff check, ruff format --check (0.16.1) and codespell (2.4.3) pass on the changed files.

🤖 Generated with Claude Code

When llms_txt_description is not set, the project description is looked up from the installed package named by `project`. It read the Description metadata field, which is the long description and usually the whole README, so the README was copied into the blockquote of every generated llms.txt. The pyproject.toml description is the Summary field. Signed-off-by: Max Freedom Pollard <[email protected]> Co-Authored-By: Claude Opus 5.5 <[email protected]>

coderabbitai · 2026-10-22T21:58:59Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Source mode: Auto
Repository: NVIDIA/sphinx-llm
Branch: main
File: .coderabbit.yaml
Commit: 2d5c7c0
Layers: Repository YAML
Review profile: CHILL
Plan: Enterprise
Run ID: a495765a-cdff-4aed-951e-d56c15c2bb21

📥 Commits

Reviewing files that changed from the base of the PR and between 2d5c7c0 and 25adb01.

📒 Files selected for processing: 3

CHANGELOG.md
src/sphinx_llm/tests/test_txt.py
src/sphinx_llm/txt.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 8 remain after this review.

📝 Summary

Summary by CodeRabbit

Bug Fixes
- The generated llms.txt now uses the package summary for its project description instead of the README’s long description. If no package summary is available, it uses the configured HTML title. This keeps the description concise and provides a fallback when package metadata is missing.

get_project_description now reads the package summary instead of the long description. A parametrized test checks that the HTML title is used when the summary is absent. The changelog records this behavior.

Changes: Project description metadata

Layer / File(s)	Summary
Project description lookup and validation `src/sphinx_llm/txt.py`, `src/sphinx_llm/tests/test_txt.py`, `CHANGELOG.md`	`get_project_description` reads the package `Summary` field. Tests check the summary and the HTML title fallback. The changelog records the change.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: jacobtomlinson

Merge Risk: ⚪ Minimal · up to 25adb

No concrete merge-blocking risk is evident in the reviewed changes.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title states the main change: the default llms.txt project description now comes from the installed package's Summary metadata instead of Description. It matches the code change in txt.py, the reg…
Description check		The description explains the bug and the fix. When llms_txt_description is unset, get_project_description() read the Description metadata field, which holds the long README body. The change reads Summ…
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files. (1 skipped: 1 …
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title states the main change: the default llms.txt project description now comes from the installed package's Summary metadata instead of Description. It matches the code change in txt.py, the regression test, and the changelog entry.

Full details: Description check

Explanation

The description explains the bug and the fix. When llms_txt_description is unset, get_project_description() read the Description metadata field, which holds the long README body. The change reads Summary instead, falls back to html_title when no summary exists, and adds a regression test and changelog entry. It also gives reproduction steps and test results.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

codecov-commenter · 2026-10-24T00:53:41Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.09%. Comparing base (21647d2) to head (25adb01).
⚠️ Report is 56 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #198       +/-   ##
===========================================
+ Coverage   81.89%   94.09%   +12.20%     
===========================================
  Files           4       17       +13     
  Lines         624     3725     +3101     
  Branches       87      345      +258     
===========================================
+ Hits          511     3505     +2994     
- Misses         84      164       +80     
- Partials       29       56       +27

Flag	Coverage Δ
unittests	`94.09% <100.00%> (+12.20%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 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.

jacobtomlinson-bot

Reviewed commit 25adb01. No blocking issues found.

The metadata lookup now uses the package Summary as documented, while preserving the explicit llms_txt_description override and existing fallback behavior. The new regression test covers both a package with a summary and one with only a README body.

Validation: uv run pytest src/sphinx_llm/tests/ — 505 passed on Python 3.15.0 / Sphinx 9.1.0.

coderabbitai Bot mentioned this pull request Oct 23, 2026

docs: add complete extension guides and simplify README #200

Open

jacobtomlinson approved these changes Oct 24, 2026

View reviewed changes

jacobtomlinson-bot reviewed Oct 24, 2026

View reviewed changes

jacobtomlinson merged commit 7ddd70a into NVIDIA:main Oct 24, 2026
21 checks passed

coderabbitai Bot mentioned this pull request Nov 5, 2026

feat: add llms_txt_details for introductory markdown #217

Merged

Navigation Menu

Repository navigation

Use the package summary as the default llms.txt description - #198

Use the package summary as the default llms.txt description#198
jacobtomlinson merged 1 commit into
NVIDIA:mainfrom
MaxFreedomPollard:fix/package-summary-description

MaxFreedomPollard commented Oct 22, 2026

Uh oh!

coderabbitai Bot commented Oct 22, 2026 •

edited

Loading

Summary by CodeRabbit

Uh oh!

codecov-commenter commented Oct 24, 2026

Uh oh!

jacobtomlinson-bot left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

MaxFreedomPollard commented Oct 22, 2026

Uh oh!

coderabbitai Bot commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

codecov-commenter commented Oct 24, 2026

Codecov Report

Uh oh!

jacobtomlinson-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

coderabbitai Bot commented Oct 22, 2026 •

edited

Loading