diff --git a/docs/conf.py b/docs/conf.py index 8f5ca6b..b465b13 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,7 +32,6 @@ extensions = [ "notfound.extension", - # "sphinx.ext.apidoc", "sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", @@ -42,6 +41,7 @@ "sphinx_design", "sphinx_issues", "sphinx_last_updated_by_git", + "sphinx_llms_txt", "sphinxext.opengraph", ] source_suffix = {".rst": "restructuredtext"} @@ -129,40 +129,6 @@ notfound_urls_prefix = "/" -# -- sphinx.ext.apidoc configuration ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/extensions/apidoc.html# -# This extension automatically generates API documentation from docstrings, -# writing the source .rst files to the specified destination directory. -# These files can't be customized to insert the SPDX headers. -# -# Steve tried copying their templates from -# `site-packages/sphinx/templates/apidoc/*.rst.jinja` to `_templates` -# and renaming them with various suffices without any luck. Editing -# the templates in their package worked, but that's not maintainable. -# -# The options are: -# 1. Don't use SPDX headers, follow icalendar with its use of sphinx.ext.apidoc, -# and .gitignore the output `reference/api` directory. -# 2. Copy and modify the templates, which may drift in the future and -# we'd never know, and use sphinx-apidoc with a new Make target. -# apidoc_modules = [ -# { -# "path": "../src/calendaring_jmap", -# "destination": "reference/api", -# "exclude_patterns": [ -# # "**/tests*", -# ], -# "separate_modules": True, -# "automodule_options": { -# "ignore-module-all", -# "members", -# "show-inheritance", -# "undoc-members", -# }, -# } -# ] - - # -- sphinx.ext.autodoc configuration ------------------------------------------------ # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html autoclass_content = "both" @@ -239,6 +205,9 @@ def setup(app): html_last_updated_fmt = "%Y-%m-%d" +# -- sphinx_llms_txt configuration ------------------------- + + # -- sphinxext.opengraph configuration ----------------------------------------- html_baseurl = os.environ.get( "READTHEDOCS_CANONICAL_URL", "https://calendaring-jmap.readthedocs.io/en/stable/" diff --git a/news/85.documentation.rst b/news/85.documentation.rst new file mode 100644 index 0000000..5a07a37 --- /dev/null +++ b/news/85.documentation.rst @@ -0,0 +1 @@ +Added :program:`sphinx-llms-txt` for generating LLMS-friendly files. @stevepiercy diff --git a/pyproject.toml b/pyproject.toml index 92b23a1..6977024 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -75,6 +75,7 @@ docs = [ "sphinx-notfound-page==1.1.0", "sphinxext-opengraph==0.13.0", "vale>=3.25.1", + "sphinx-llms-txt>=0.7.1", ] [project.urls] diff --git a/uv.lock b/uv.lock index 21ffa54..79b3442 100644 --- a/uv.lock +++ b/uv.lock @@ -1,5 +1,5 @@ version = 1 -revision = 3 +revision = 5 requires-python = ">=3.11" resolution-markers = [ "python_full_version >= '3.13'", @@ -101,6 +101,7 @@ dev = [ { name = "sphinx-design" }, { name = "sphinx-issues" }, { name = "sphinx-last-updated-by-git" }, + { name = "sphinx-llms-txt" }, { name = "sphinx-notfound-page" }, { name = "sphinxext-opengraph" }, { name = "towncrier" }, @@ -120,6 +121,7 @@ docs = [ { name = "sphinx-design" }, { name = "sphinx-issues" }, { name = "sphinx-last-updated-by-git" }, + { name = "sphinx-llms-txt" }, { name = "sphinx-notfound-page" }, { name = "sphinxext-opengraph" }, { name = "vale" }, @@ -167,12 +169,13 @@ dev = [ { name = "sphinx-design", specifier = ">=0.6.1" }, { name = "sphinx-issues", specifier = "==6.0.0" }, { name = "sphinx-last-updated-by-git", specifier = "==0.3.8" }, + { name = "sphinx-llms-txt", specifier = ">=0.7.1" }, { name = "sphinx-notfound-page", specifier = "==1.1.0" }, { name = "sphinxext-opengraph", specifier = "==0.13.0" }, { name = "towncrier", specifier = "==26.9.0" }, { name = "types-pyyaml", specifier = "==6.0.12.20260906" }, { name = "types-requests", specifier = "==2.33.0.20260906" }, - { name = "vale", specifier = ">=3.25.1" }, + { name = "vale", specifier = ">=3.25.1.0" }, ] docs = [ { name = "pydata-sphinx-theme", specifier = ">=0.19.0" }, @@ -183,9 +186,10 @@ docs = [ { name = "sphinx-design", specifier = ">=0.6.1" }, { name = "sphinx-issues", specifier = "==6.0.0" }, { name = "sphinx-last-updated-by-git", specifier = "==0.3.8" }, + { name = "sphinx-llms-txt", specifier = ">=0.7.1" }, { name = "sphinx-notfound-page", specifier = "==1.1.0" }, { name = "sphinxext-opengraph", specifier = "==0.13.0" }, - { name = "vale", specifier = ">=3.25.1" }, + { name = "vale", specifier = ">=3.25.1.0" }, ] formatting = [ { name = "pre-commit" }, @@ -1285,23 +1289,23 @@ resolution-markers = [ "python_full_version < '3.11.5'", ] dependencies = [ - { name = "alabaster", marker = "python_full_version < '3.12'" }, - { name = "babel", marker = "python_full_version < '3.12'" }, - { name = "colorama", marker = "python_full_version < '3.12' and sys_platform == 'win32'" }, - { name = "docutils", version = "0.22.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, - { name = "imagesize", marker = "python_full_version < '3.12'" }, - { name = "jinja2", marker = "python_full_version < '3.12'" }, - { name = "packaging", marker = "python_full_version < '3.12'" }, - { name = "pygments", marker = "python_full_version < '3.12'" }, - { name = "requests", marker = "python_full_version < '3.12'" }, - { name = "roman-numerals", marker = "python_full_version < '3.12'" }, - { name = "snowballstemmer", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-applehelp", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-devhelp", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-htmlhelp", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-jsmath", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-qthelp", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-serializinghtml", marker = "python_full_version < '3.12'" }, + { name = "alabaster" }, + { name = "babel" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "docutils", version = "0.22.4", source = { registry = "https://pypi.org/simple" } }, + { name = "imagesize" }, + { name = "jinja2" }, + { name = "packaging" }, + { name = "pygments" }, + { name = "requests" }, + { name = "roman-numerals" }, + { name = "snowballstemmer" }, + { name = "sphinxcontrib-applehelp" }, + { name = "sphinxcontrib-devhelp" }, + { name = "sphinxcontrib-htmlhelp" }, + { name = "sphinxcontrib-jsmath" }, + { name = "sphinxcontrib-qthelp" }, + { name = "sphinxcontrib-serializinghtml" }, ] sdist = { url = "https://files.pythonhosted.org/packages/42/50/a8c6ccc36d5eacdfd7913ddccd15a9cee03ecafc5ee2bc40e1f168d85022/sphinx-9.0.4.tar.gz", hash = "sha256:594ef59d042972abbc581d8baa577404abe4e6c3b04ef61bd7fc2acbd51f3fa3", size = 8710502, upload-time = "2025-12-04T07:45:27.343Z" } wheels = [ @@ -1316,23 +1320,23 @@ resolution-markers = [ "python_full_version == '3.12.*'", ] dependencies = [ - { name = "alabaster", marker = "python_full_version == '3.12.*'" }, - { name = "babel", marker = "python_full_version == '3.12.*'" }, - { name = "colorama", marker = "python_full_version == '3.12.*' and sys_platform == 'win32'" }, - { name = "docutils", version = "0.22.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.12.*'" }, - { name = "imagesize", marker = "python_full_version == '3.12.*'" }, - { name = "jinja2", marker = "python_full_version == '3.12.*'" }, - { name = "packaging", marker = "python_full_version == '3.12.*'" }, - { name = "pygments", marker = "python_full_version == '3.12.*'" }, - { name = "requests", marker = "python_full_version == '3.12.*'" }, - { name = "roman-numerals", marker = "python_full_version == '3.12.*'" }, - { name = "snowballstemmer", marker = "python_full_version == '3.12.*'" }, - { name = "sphinxcontrib-applehelp", marker = "python_full_version == '3.12.*'" }, - { name = "sphinxcontrib-devhelp", marker = "python_full_version == '3.12.*'" }, - { name = "sphinxcontrib-htmlhelp", marker = "python_full_version == '3.12.*'" }, - { name = "sphinxcontrib-jsmath", marker = "python_full_version == '3.12.*'" }, - { name = "sphinxcontrib-qthelp", marker = "python_full_version == '3.12.*'" }, - { name = "sphinxcontrib-serializinghtml", marker = "python_full_version == '3.12.*'" }, + { name = "alabaster" }, + { name = "babel" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "docutils", version = "0.22.4", source = { registry = "https://pypi.org/simple" } }, + { name = "imagesize" }, + { name = "jinja2" }, + { name = "packaging" }, + { name = "pygments" }, + { name = "requests" }, + { name = "roman-numerals" }, + { name = "snowballstemmer" }, + { name = "sphinxcontrib-applehelp" }, + { name = "sphinxcontrib-devhelp" }, + { name = "sphinxcontrib-htmlhelp" }, + { name = "sphinxcontrib-jsmath" }, + { name = "sphinxcontrib-qthelp" }, + { name = "sphinxcontrib-serializinghtml" }, ] sdist = { url = "https://files.pythonhosted.org/packages/fc/73/567727fc8c8d85bc3adc88a246e12937cfda8d565cf1d80e85bceaa61fe5/sphinx-9.1.1.tar.gz", hash = "sha256:48b627f02908f22c601b3ba9c7b17265b4f315dd05c8bc64cd4da41183f44fbc", size = 8725638, upload-time = "2026-10-20T00:41:13.96Z" } wheels = [ @@ -1347,23 +1351,23 @@ resolution-markers = [ "python_full_version >= '3.13'", ] dependencies = [ - { name = "alabaster", marker = "python_full_version >= '3.13'" }, - { name = "babel", marker = "python_full_version >= '3.13'" }, - { name = "colorama", marker = "python_full_version >= '3.13' and sys_platform == 'win32'" }, - { name = "docutils", version = "0.23", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.13'" }, - { name = "imagesize", marker = "python_full_version >= '3.13'" }, - { name = "jinja2", marker = "python_full_version >= '3.13'" }, - { name = "packaging", marker = "python_full_version >= '3.13'" }, - { name = "pygments", marker = "python_full_version >= '3.13'" }, - { name = "requests", marker = "python_full_version >= '3.13'" }, - { name = "roman-numerals", marker = "python_full_version >= '3.13'" }, - { name = "snowballstemmer", marker = "python_full_version >= '3.13'" }, - { name = "sphinxcontrib-applehelp", marker = "python_full_version >= '3.13'" }, - { name = "sphinxcontrib-devhelp", marker = "python_full_version >= '3.13'" }, - { name = "sphinxcontrib-htmlhelp", marker = "python_full_version >= '3.13'" }, - { name = "sphinxcontrib-jsmath", marker = "python_full_version >= '3.13'" }, - { name = "sphinxcontrib-qthelp", marker = "python_full_version >= '3.13'" }, - { name = "sphinxcontrib-serializinghtml", marker = "python_full_version >= '3.13'" }, + { name = "alabaster" }, + { name = "babel" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "docutils", version = "0.23", source = { registry = "https://pypi.org/simple" } }, + { name = "imagesize" }, + { name = "jinja2" }, + { name = "packaging" }, + { name = "pygments" }, + { name = "requests" }, + { name = "roman-numerals" }, + { name = "snowballstemmer" }, + { name = "sphinxcontrib-applehelp" }, + { name = "sphinxcontrib-devhelp" }, + { name = "sphinxcontrib-htmlhelp" }, + { name = "sphinxcontrib-jsmath" }, + { name = "sphinxcontrib-qthelp" }, + { name = "sphinxcontrib-serializinghtml" }, ] sdist = { url = "https://files.pythonhosted.org/packages/64/d4/413466f0be8b1cb0e3e43893a148b96d7462d0923d82b4166b21afc5f30c/sphinx-9.2.0.tar.gz", hash = "sha256:90470459f3cab15d9dfed146c71cf77694b0445df17b2e0e69059cb9f7fc9ee4", size = 8782438, upload-time = "2026-10-21T00:05:15.019Z" } wheels = [ @@ -1398,7 +1402,7 @@ resolution-markers = [ "python_full_version < '3.11.5'", ] dependencies = [ - { name = "sphinx", version = "9.0.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, + { name = "sphinx", version = "9.0.4", source = { registry = "https://pypi.org/simple" } }, ] sdist = { url = "https://files.pythonhosted.org/packages/1d/f6/bdd93582b2aaad2cfe9eb5695a44883c8bc44572dd3c351a947acbb13789/sphinx_autodoc_typehints-3.6.1.tar.gz", hash = "sha256:fa0b686ae1b85965116c88260e5e4b82faec3687c2e94d6a10f9b36c3743e2fe", size = 37563, upload-time = "2026-01-02T15:23:46.543Z" } wheels = [ @@ -1414,9 +1418,9 @@ resolution-markers = [ "python_full_version == '3.12.*'", ] dependencies = [ - { name = "sphinx", version = "9.1.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.12.*'" }, + { name = "sphinx", version = "9.1.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" }, { name = "sphinx", version = "9.2.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.13'" }, - { name = "typing-extensions", marker = "python_full_version >= '3.12' and python_full_version < '3.15'" }, + { name = "typing-extensions", marker = "python_full_version < '3.15'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/9e/a9/cfe13ff89678c6d310a8a9060333b7823bae1dbce9615c7032be89aaec20/sphinx_autodoc_typehints-3.17.4.tar.gz", hash = "sha256:a5ddd545192380292f13dd9fc232717a0925fbc66617bc51b3db1e0480db0fec", size = 511398, upload-time = "2026-10-27T19:18:44.225Z" } wheels = [ @@ -1479,6 +1483,20 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e1/fb/e496f16fa11fbe2dbdd0b5e306ede153dfed050aae4766fc89d500720dc7/sphinx_last_updated_by_git-0.3.8-py3-none-any.whl", hash = "sha256:6382c8285ac1f222483a58569b78c0371af5e55f7fbf9c01e5e8a72d6fdfa499", size = 8580, upload-time = "2024-08-11T07:15:53.244Z" }, ] +[[package]] +name = "sphinx-llms-txt" +version = "0.7.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx", version = "9.0.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, + { name = "sphinx", version = "9.1.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.12.*'" }, + { name = "sphinx", version = "9.2.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.13'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/d3/dd/6d7fa7d6f51ee20959f1734cdbd62e99880dcd87576ce554d4bb8aaabdd7/sphinx_llms_txt-0.7.1.tar.gz", hash = "sha256:b5cefec19d3fd56670aa4a28917d17d32b22c61a9feadbab8564ad11e932f5c0", size = 32464, upload-time = "2025-12-16T22:31:26.379Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c2/17/a751012a0910e3c3afa41a5d40bdf00132466d072d25891ae7ec1f70dafd/sphinx_llms_txt-0.7.1-py3-none-any.whl", hash = "sha256:8f1cfcfe5897f5be118792f33f73eeb04cbbf66fc60c4c15982ec59252522263", size = 22545, upload-time = "2025-12-16T22:31:25.075Z" }, +] + [[package]] name = "sphinx-notfound-page" version = "1.1.0" @@ -1736,11 +1754,11 @@ wheels = [ [[package]] name = "vale" -version = "3.25.1.0" +version = "3.26.0.1" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/64/f6/c8c3076c7d203cb9a1ae53cc7fb858bce9b47de9fb52a748f488c0fa16db/vale-3.25.1.0.tar.gz", hash = "sha256:4bbe325c196544c3b5f6c948cfe030d01fc5f127978d3092ae8d83d0ec59ae30", size = 5370, upload-time = "2026-10-23T07:26:39.951Z" } +sdist = { url = "https://files.pythonhosted.org/packages/c0/42/183efef5abed6af360d8ac128692a156506f8471014279ed9f05ddae8046/vale-3.26.0.1.tar.gz", hash = "sha256:1db9c31b009a183f15c596bb17a889c6c3f1e88950e8fc307ea1dea17a63cd80", size = 5914, upload-time = "2026-11-02T08:00:02.829Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/4a/10/7fc3224c4f28de3fec61ef55481ee352323d890f9c2501682770001585f3/vale-3.25.1.0-py3-none-any.whl", hash = "sha256:f93656a84d4d58ee38d89426d7caa70c15defa2b726a0bf06f77f266f3b2c016", size = 5943, upload-time = "2026-10-23T07:26:38.782Z" }, + { url = "https://files.pythonhosted.org/packages/13/62/3d223a82abd0c6eb8f9d4885d7f818df99c649990c2031312019f7711c64/vale-3.26.0.1-py3-none-any.whl", hash = "sha256:d5cd1a48b6da7607f1849444259f75307b539796b74662cb29f2b926850c670e", size = 6380, upload-time = "2026-11-02T08:00:01.528Z" }, ] [[package]]