From 4208760e8393d745ff608450d4e0afd5e013aa6b Mon Sep 17 00:00:00 2001 From: Aaron Spring Date: Wed, 17 Jun 2026 09:48:28 +0200 Subject: [PATCH 1/3] Make docs discoverable by LLMs and coding agents (llms.txt) Following Jacob Tomlinson's PyData talk on marketing open source projects to LLMs (https://youtu.be/bRDtplyhRYw), make xskillscore documentation easy for coding agents to discover and parse: - Generate llms.txt (summary) and llms-full.txt (full docs as a single context-efficient text file) during the Sphinx HTML build via the sphinx-llms-txt extension, with a project title/summary and absolute links driven by html_baseurl. - Add documentation breadcrumbs to the package __init__ so agents reading the source are pointed at the docs and the llms.txt files. - Add sphinx-llms-txt to the docs build environments (ci/doc.yml and the `complete` optional-dependencies extra). Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.rst | 13 +++++++++++++ ci/doc.yml | 1 + docs/source/conf.py | 18 ++++++++++++++++++ pyproject.toml | 1 + xskillscore/__init__.py | 13 +++++++++++++ 5 files changed, 46 insertions(+) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index e7f4fd45..1c2c11e6 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -3,6 +3,19 @@ Changelog History ================= +.. _whats-new.unreleased: + +Unreleased +---------- + +Documentation +~~~~~~~~~~~~~ +- Made the documentation discoverable and parseable by LLMs and coding agents by + generating ``llms.txt`` and ``llms-full.txt`` during the docs build (via + ``sphinx-llms-txt``) and adding documentation breadcrumbs to the package + ``__init__``. (:pr:`451`) `Aaron Spring`_ + + xskillscore v0.0.29 (2026-02-18) -------------------------------- diff --git a/ci/doc.yml b/ci/doc.yml index d996d4e1..cb1c89ed 100644 --- a/ci/doc.yml +++ b/ci/doc.yml @@ -21,6 +21,7 @@ dependencies: - sphinx_rtd_theme >=1.0 - sphinx-autosummary-accessors - sphinx-copybutton + - sphinx-llms-txt - statsmodels - xarray >=2023.4.0 - xhistogram>=0.3.2 diff --git a/docs/source/conf.py b/docs/source/conf.py index f08aa3f1..fe190e88 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -41,8 +41,22 @@ "IPython.sphinxext.ipython_console_highlighting", "nbsphinx", "sphinx_autosummary_accessors", + "sphinx_llms_txt", ] +# -- Options for LLM-friendly output (sphinx-llms-txt) ----------------------- +# Generate ``llms.txt`` (a summary) and ``llms-full.txt`` (the full docs as a +# single context-efficient text file) during the HTML build so coding agents +# and LLMs can discover and parse the documentation. See +# https://sphinx-llms-txt.readthedocs.io and the llms.txt standard at +# https://llmstxt.org. +llms_txt_title = "xskillscore: Metrics for verifying forecasts" +llms_txt_summary = ( + "xskillscore is a Python package for computing deterministic and " + "probabilistic forecast verification metrics on xarray objects, with " + "Dask support for parallel computing." +) + extlinks = { "issue": ("https://github.com/xarray-contrib/xskillscore/issues/%s", "GH%s"), "pr": ("https://github.com/xarray-contrib/xskillscore/pull/%s", "GH%s"), @@ -99,6 +113,10 @@ # html_theme = "sphinx_rtd_theme" +# Base URL of the published docs. Used by sphinx-llms-txt to build absolute +# links in the generated llms.txt files. +html_baseurl = "https://xskillscore.readthedocs.io/en/stable/" + # Can add below once we have a logo. # html_logo = 'images/esmtools-logo.png' # html_theme_options = {'logo_only': True, 'style_nav_header_background': '#fcfcfc'} diff --git a/pyproject.toml b/pyproject.toml index 3c3aef2c..ab1d1ec4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -60,6 +60,7 @@ complete = [ "sphinx >=6.0.0", "sphinx-autosummary-accessors", "sphinx-copybutton", + "sphinx-llms-txt", "sphinx-rtd-theme>=1.0", ] diff --git a/xskillscore/__init__.py b/xskillscore/__init__.py index d51f7855..c6ef006b 100644 --- a/xskillscore/__init__.py +++ b/xskillscore/__init__.py @@ -1,3 +1,16 @@ +"""xskillscore: Metrics for verifying forecasts. + +xskillscore computes deterministic and probabilistic forecast verification +metrics on :py:mod:`xarray` objects, with Dask support for parallel computing. + +Documentation breadcrumbs (for humans and LLMs/coding agents): + +- Documentation: https://xskillscore.readthedocs.io/en/stable/ +- LLM-friendly docs: https://xskillscore.readthedocs.io/en/stable/llms.txt + (full text: https://xskillscore.readthedocs.io/en/stable/llms-full.txt) +- Source: https://github.com/xarray-contrib/xskillscore +""" + from importlib.metadata import version, PackageNotFoundError # ruff: noqa From 8ba7a39e851eaf9cfbc80b6dae9a5a01e9325ab4 Mon Sep 17 00:00:00 2001 From: Aaron Spring Date: Wed, 17 Jun 2026 09:51:28 +0200 Subject: [PATCH 2/3] Use NVIDIA sphinx-llm to generate llms.txt / llms-full.txt Switch from sphinx-llms-txt to NVIDIA's sphinx-llm package (the `sphinx_llm.txt` extension). It uses the markdown builder to emit true markdown: llms.txt (sitemap), llms-full.txt (full docs) and per-page .md files, following the llms.txt standard. - conf.py: enable `sphinx_llm.txt`; set `llms_txt_description` (title comes from the project name). Drop the html_baseurl and llms_txt_title/summary keys that were specific to sphinx-llms-txt. - ci/doc.yml and the `complete` extra: depend on sphinx-llm. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.rst | 4 ++-- ci/doc.yml | 2 +- docs/source/conf.py | 21 ++++++++------------- pyproject.toml | 2 +- 4 files changed, 12 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 1c2c11e6..dc58bcb6 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -11,8 +11,8 @@ Unreleased Documentation ~~~~~~~~~~~~~ - Made the documentation discoverable and parseable by LLMs and coding agents by - generating ``llms.txt`` and ``llms-full.txt`` during the docs build (via - ``sphinx-llms-txt``) and adding documentation breadcrumbs to the package + generating ``llms.txt``, ``llms-full.txt`` and per-page markdown during the docs + build (via ``sphinx-llm``) and adding documentation breadcrumbs to the package ``__init__``. (:pr:`451`) `Aaron Spring`_ diff --git a/ci/doc.yml b/ci/doc.yml index cb1c89ed..53e3428e 100644 --- a/ci/doc.yml +++ b/ci/doc.yml @@ -21,7 +21,7 @@ dependencies: - sphinx_rtd_theme >=1.0 - sphinx-autosummary-accessors - sphinx-copybutton - - sphinx-llms-txt + - sphinx-llm - statsmodels - xarray >=2023.4.0 - xhistogram>=0.3.2 diff --git a/docs/source/conf.py b/docs/source/conf.py index fe190e88..5e06f03b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -41,17 +41,16 @@ "IPython.sphinxext.ipython_console_highlighting", "nbsphinx", "sphinx_autosummary_accessors", - "sphinx_llms_txt", + "sphinx_llm.txt", ] -# -- Options for LLM-friendly output (sphinx-llms-txt) ----------------------- -# Generate ``llms.txt`` (a summary) and ``llms-full.txt`` (the full docs as a -# single context-efficient text file) during the HTML build so coding agents -# and LLMs can discover and parse the documentation. See -# https://sphinx-llms-txt.readthedocs.io and the llms.txt standard at -# https://llmstxt.org. -llms_txt_title = "xskillscore: Metrics for verifying forecasts" -llms_txt_summary = ( +# -- Options for LLM-friendly output (sphinx-llm) --------------------------- +# Generate ``llms.txt`` (a sitemap), ``llms-full.txt`` (the full docs as a +# single context-efficient markdown file) and per-page ``.md`` files during +# the HTML build so coding agents and LLMs can discover and parse the +# documentation. See https://github.com/NVIDIA/sphinx-llm and the llms.txt +# standard at https://llmstxt.org. +llms_txt_description = ( "xskillscore is a Python package for computing deterministic and " "probabilistic forecast verification metrics on xarray objects, with " "Dask support for parallel computing." @@ -113,10 +112,6 @@ # html_theme = "sphinx_rtd_theme" -# Base URL of the published docs. Used by sphinx-llms-txt to build absolute -# links in the generated llms.txt files. -html_baseurl = "https://xskillscore.readthedocs.io/en/stable/" - # Can add below once we have a logo. # html_logo = 'images/esmtools-logo.png' # html_theme_options = {'logo_only': True, 'style_nav_header_background': '#fcfcfc'} diff --git a/pyproject.toml b/pyproject.toml index ab1d1ec4..c05c56ba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -60,7 +60,7 @@ complete = [ "sphinx >=6.0.0", "sphinx-autosummary-accessors", "sphinx-copybutton", - "sphinx-llms-txt", + "sphinx-llm", "sphinx-rtd-theme>=1.0", ] From fdaa9c9a761343dc91ae8385ab404efb259b30cb Mon Sep 17 00:00:00 2001 From: Aaron Spring Date: Wed, 17 Jun 2026 10:02:17 +0200 Subject: [PATCH 3/3] Add Context7 docs badge to README and docs landing page Link to https://context7.com/xarray-contrib/xskillscore so users and coding agents can find the LLM-indexed documentation. Uses a shields.io static badge in Context7 brand colour. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.rst | 2 ++ README.rst | 6 +++++- docs/source/index.rst | 3 +++ 3 files changed, 10 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index dc58bcb6..7a86689f 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -14,6 +14,8 @@ Documentation generating ``llms.txt``, ``llms-full.txt`` and per-page markdown during the docs build (via ``sphinx-llm``) and adding documentation breadcrumbs to the package ``__init__``. (:pr:`451`) `Aaron Spring`_ +- Added a `Context7 `_ documentation + badge to the README and docs landing page. (:pr:`451`) `Aaron Spring`_ xskillscore v0.0.29 (2026-02-18) diff --git a/README.rst b/README.rst index 9fab7ba0..e903c858 100644 --- a/README.rst +++ b/README.rst @@ -2,7 +2,7 @@ xskillscore: Metrics for verifying forecasts ============================================ +---------------------------+-------------------------------------------+ -| Documentation and Support | |docs| |binder| | +| Documentation and Support | |docs| |context7| |binder| | +---------------------------+-------------------------------------------+ | Open Source | |pypi| |conda-forge| |license| |zenodo| | +---------------------------+-------------------------------------------+ @@ -56,6 +56,10 @@ We are indebted to the **xarray** community for their `advice