Make docs discoverable by LLMs and coding agents (sphinx-llm)

CHANGELOG.rst

@@ -3,6 +3,8 @@ Changelog History
 =================
 
 
+.. _whats-new.unreleased:
+
 xskillscore vNext (unreleased)
 ------------------------------
 
@@ -11,6 +13,15 @@ Breaking Changes
 - Dropped support for Python 3.9. The minimum supported version is now Python 3.10.
   `Aaron Spring`_
 
+Documentation
+~~~~~~~~~~~~~
+- Made the documentation discoverable and parseable by LLMs and coding agents by
+  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 <https://context7.com/xarray-contrib/xskillscore>`_ documentation
+  badge to the README and docs landing page. (:pr:`451`) `Aaron Spring`_
+
 Internal Changes
 ~~~~~~~~~~~~~~~~
 - Bumped GitHub Actions to versions running on Node.js 24 (``actions/checkout@v5``,

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 <https://groups.go
         :target: https://anaconda.org/conda-forge/xskillscore
         :alt: conda-forge
 
+.. |context7| image:: https://img.shields.io/badge/Context7-Docs-6366f1?logo=readthedocs&logoColor=white
+        :target: https://context7.com/xarray-contrib/xskillscore
+        :alt: Context7 Documentation
+
 .. |docs| image:: https://img.shields.io/readthedocs/xskillscore/stable.svg?style=flat
         :target: https://xskillscore.readthedocs.io/en/stable/?badge=stable
         :alt: Documentation Status

ci/doc.yml

@@ -21,6 +21,7 @@ dependencies:
   - sphinx_rtd_theme >=1.0
   - sphinx-autosummary-accessors
   - sphinx-copybutton
+  - sphinx-llm
   - statsmodels
   - xarray >=2023.4.0
   - xhistogram>=0.3.2

docs/source/conf.py

@@ -41,8 +41,21 @@
     "IPython.sphinxext.ipython_console_highlighting",
     "nbsphinx",
     "sphinx_autosummary_accessors",
+    "sphinx_llm.txt",
 ]
 
+# -- 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."
+)
+
 extlinks = {
     "issue": ("https://github.com/xarray-contrib/xskillscore/issues/%s", "GH%s"),
     "pr": ("https://github.com/xarray-contrib/xskillscore/pull/%s", "GH%s"),

docs/source/index.rst

@@ -1,32 +1,16 @@
 xskillscore: Metrics for verifying forecasts
 ============================================
 
-.. image:: https://github.com/xarray-contrib/xskillscore/actions/workflows/xskillscore_testing.yml/badge.svg
-   :target: https://github.com/xarray-contrib/xskillscore/actions/workflows/xskillscore_testing.yml
-
-.. image:: https://github.com/xarray-contrib/xskillscore/actions/workflows/upstream-dev-ci.yml/badge.svg
-   :target: https://github.com/xarray-contrib/xskillscore/actions/workflows/upstream-dev-ci.yml
-
-.. image:: https://results.pre-commit.ci/badge/github/xarray-contrib/xskillscore/main.svg
-   :target: https://results.pre-commit.ci/latest/github/xarray-contrib/xskillscore/main
-
-.. image:: https://img.shields.io/pypi/v/xskillscore.svg
-   :target: https://pypi.python.org/pypi/xskillscore/
-
-.. image:: https://anaconda.org/conda-forge/xskillscore/badges/version.svg
-   :target: https://anaconda.org/conda-forge/xskillscore/
-
-.. image:: https://codecov.io/gh/xarray-contrib/xskillscore/branch/main/graph/badge.svg
-   :target: https://codecov.io/gh/xarray-contrib/xskillscore
-
-.. image:: https://img.shields.io/conda/dn/conda-forge/xskillscore.svg
-   :target: https://anaconda.org/conda-forge/xskillscore
-
-.. image:: https://mybinder.org/badge_logo.svg
-   :target: https://mybinder.org/v2/gh/raybellwaves/xskillscore-tutorial/master?urlpath=lab
-
-.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5173152.svg
-   :target: https://doi.org/10.5281/zenodo.5173152
++---------------------------+-------------------------------------------+
+| Documentation and Support | |docs| |context7| |binder|                |
++---------------------------+-------------------------------------------+
+| Open Source               | |pypi| |conda-forge| |conda-downloads|    |
+|                           | |license| |zenodo|                        |
++---------------------------+-------------------------------------------+
+| Coding Standards          | |codecov| |pre-commit|                    |
++---------------------------+-------------------------------------------+
+| Development Status        | |status| |testing| |upstream|             |
++---------------------------+-------------------------------------------+
 
 Installation
 ============
@@ -79,3 +63,55 @@ You can also install the bleeding edge (pre-release versions) by running:
    release_procedure
    related-projects
    contributors
+
+.. |binder| image:: https://mybinder.org/badge_logo.svg
+        :target: https://mybinder.org/v2/gh/raybellwaves/xskillscore-tutorial/master?urlpath=lab
+        :alt: Binder
+
+.. |codecov| image:: https://codecov.io/gh/xarray-contrib/xskillscore/branch/main/graph/badge.svg
+        :target: https://codecov.io/gh/xarray-contrib/xskillscore
+        :alt: Codecov
+
+.. |conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/xskillscore.svg
+        :target: https://anaconda.org/conda-forge/xskillscore
+        :alt: conda-forge
+
+.. |conda-downloads| image:: https://img.shields.io/conda/dn/conda-forge/xskillscore.svg
+        :target: https://anaconda.org/conda-forge/xskillscore
+        :alt: conda-forge downloads
+
+.. |context7| image:: https://img.shields.io/badge/Context7-Docs-6366f1?logo=readthedocs&logoColor=white
+        :target: https://context7.com/xarray-contrib/xskillscore
+        :alt: Context7 Documentation
+
+.. |docs| image:: https://img.shields.io/readthedocs/xskillscore/stable.svg?style=flat
+        :target: https://xskillscore.readthedocs.io/en/stable/?badge=stable
+        :alt: Documentation Status
+
+.. |license| image:: https://img.shields.io/github/license/xarray-contrib/xncml.svg
+        :target: https://github.com/xarray-contrib/xncml/blob/main/LICENSE
+        :alt: License
+
+.. |pre-commit| image:: https://results.pre-commit.ci/badge/github/xarray-contrib/xskillscore/main.svg
+        :target: https://results.pre-commit.ci/latest/github/xarray-contrib/xskillscore/main
+        :alt: Pre-Commit
+
+.. |pypi| image:: https://img.shields.io/pypi/v/xskillscore.svg
+        :target: https://pypi.python.org/pypi/xskillscore/
+        :alt: PyPI
+
+.. |status| image:: https://www.repostatus.org/badges/latest/active.svg
+        :target: https://www.repostatus.org/#active
+        :alt: Project Status: Active – The project has reached a stable, usable state and is being actively developed.
+
+.. |testing| image:: https://github.com/xarray-contrib/xskillscore/actions/workflows/xskillscore_testing.yml/badge.svg
+        :target: https://github.com/xarray-contrib/xskillscore/actions/workflows/xskillscore_testing.yml
+        :alt: Testing
+
+.. |upstream| image:: https://github.com/xarray-contrib/xskillscore/actions/workflows/upstream-dev-ci.yml/badge.svg
+        :target: https://github.com/xarray-contrib/xskillscore/actions/workflows/upstream-dev-ci.yml
+        :alt: Upstream Testing
+
+.. |zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5173152.svg
+        :target: https://doi.org/10.5281/zenodo.5173152
+        :alt: Zenodo DOI

pyproject.toml

@@ -59,6 +59,7 @@ complete = [
     "sphinx >=6.0.0",
     "sphinx-autosummary-accessors",
     "sphinx-copybutton",
+    "sphinx-llm",
     "sphinx-rtd-theme>=1.0",
 ]