feat: add default support for sphinx-llm

CHANGELOG.md

@@ -2,32 +2,43 @@
 
 ## Upcoming
 
-* Remove reuse directory
-* Rename `.sphinx/` directory to `_dev/`.
-* Separate default configuration for copyright and license statements.
+* Add an `AUTOBUILD_EXTRA_OPTS` variable to extend sphinx-autobuild options for `make run`
+* Add default support for the sphinx-llm extension
+* Pin dependencies to major versions
+* Remove `reuse/` directory
+* Rename `.sphinx/` directory to `_dev/`
+* Add default configuration for copyright and license statements
+
+### Changed
+
+* `docs/conf.py`  [#562](https://github.com/canonical/sphinx-docs-starter-pack/pull/562), [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576), [#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
+* `docs/Makefile` [#575](https://github.com/canonical/sphinx-docs-starter-pack/pull/575), [#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590)
+* `docs/requirements.txt` [#590]([#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590))
+* `docs/reuse/` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576)
+* `docs/.sphinx/` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
+* `docs/_templates/footer.html` [#594](https://github.com/canonical/sphinx-docs-starter-pack/pull/594)
+* `docs/requirements.txt` [#596](https://github.com/canonical/sphinx-docs-starter-pack/pull/596)
+* `docs/redirects.txt` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
+
+## 1.6
+
 * Fix the handling of non-zero exit codes from pymarkdownlnt.
 * Add a how-to guide about testing the Ulwazi theme.
 * Move the Python virtual environment from `docs/.sphinx/venv` to `docs/.venv`.
 * Make rediraffe the default extension for page redirects
 * Add default templates for the Canonical cookie banner and Google Analytics.
-* Add an `AUTOBUILD_EXTRA_OPTS` variable to extend sphinx-autobuild options for `make run`.
-* Pin dependencies to major versions.
 
 ### Changed
 
-* `docs/reuse/` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576)
-* `docs/.sphinx/` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
-* `docs/conf.py` [#562](https://github.com/canonical/sphinx-docs-starter-pack/pull/562), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
 * `.github/workflows/check-removed-urls.yml` [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552)
 * `.github/workflows/sphinx-python-dependency-build-checks.yml` [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552)
 * `docs/.gitignore` [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
 * `docs/.sphinx/.wordlist.txt` [#520](https://github.com/canonical/sphinx-docs-starter-pack/pull/520)
-* `docs/conf.py` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558), [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558), [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576)
+* `docs/conf.py` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558), [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558)
 * `docs/Makefile` [#551](https://github.com/canonical/sphinx-docs-starter-pack/pull/551), [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552)
-* `docs/redirects.txt` [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
+* `docs/redirects.txt` [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558)
 * `docs/_templates/header.html` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549)
-* `docs/_templates/footer.html` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549), [#594](https://github.com/canonical/sphinx-docs-starter-pack/pull/594)
-* `docs/requirements.txt` [#596](https://github.com/canonical/sphinx-docs-starter-pack/pull/596)
+* `docs/_templates/footer.html` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549)
 
 ## 1.5
 

docs/.custom_wordlist.txt

@@ -20,13 +20,15 @@ Kompare
 lang
 LaTeX
 latexmk
+LLMs?
 Multipass
 npm
 otf
 plantuml
 PNG
 Pygments
 pymarkdown
+pymarkdownlnt
 QEMU
 Rockcraft
 readthedocs

docs/Makefile

@@ -10,7 +10,7 @@ SPHINX_OPTS      ?= -c . -d $(DEV_DIR)/.doctrees -j auto
 SPHINX_BUILD     ?= $(DOCS_VENVDIR)/bin/sphinx-build
 SPHINX_HOST      ?= 127.0.0.1
 SPHINX_PORT      ?= 8000
-SPHINX_AUTOBUILD_OPTS ?=
+SPHINX_AUTOBUILD_OPTS ?= -D=llms_txt_enabled=0
 DOCS_VENVDIR     ?= .venv
 DOCS_VENV        ?= $(DOCS_VENVDIR)/bin/activate
 DOCS_SOURCEDIR   ?= .

docs/conf.py

@@ -1,5 +1,7 @@
 import datetime
 import os
+import textwrap
+
 import yaml
 
 # Configuration for the Sphinx documentation builder.
@@ -118,25 +120,20 @@
     # Docs branch in the repo; used in links for viewing the source files
     #
     # TODO: To customise the branch, uncomment and update as needed.
-    'repo_default_branch': 'main',
+    "repo_default_branch": "main",
     # Docs location in the repo; used in links for viewing the source files
     #
-
-
     # TODO: To customise the directory, uncomment and update as needed.
     "repo_folder": "/docs/",
     # TODO: To enable or disable the Previous / Next buttons at the bottom of pages
     # Valid options: none, prev, next, both
     # "sequential_nav": "both",
     # TODO: To enable listing contributors on individual pages, set to True
     "display_contributors": False,
-
-    # Required for feedback button   
-    'github_issues': 'enabled',
-
+    # Required for feedback button
+    "github_issues": "enabled",
     # Inherit the author value
     "author": author,
-
     # The Starter Pack uses CC-BY-SA as the license
     #
     # TODO: If your docs need another license, specify it instead of 'CC-BY-SA'.
@@ -148,7 +145,6 @@
     #
     # TODO: If your documentation is a part of the code repository of your project,
     #       it inherits the code license instead; specify it instead of 'CC-BY-SA'.
-
     "license": {
         "name": "CC-BY-SA-3.0",
         "url": "https://github.com/canonical/sphinx-docs-starter-pack/blob/main/LICENSE",
@@ -190,7 +186,7 @@
 
 # sphinx-sitemap uses html_baseurl to generate the full URL for each page:
 
-sitemap_url_scheme = '{link}'
+sitemap_url_scheme = "{link}"
 
 # Include `lastmod` dates in the sitemap:
 
@@ -199,9 +195,9 @@
 # Exclude generated pages from the sitemap:
 
 sitemap_excludes = [
-    '404/',
-    'genindex/',
-    'search/',
+    "404/",
+    "genindex/",
+    "search/",
 ]
 
 # TODO: Add more pages to sitemap_excludes if needed. Wildcards are supported.
@@ -231,6 +227,25 @@
 rediraffe_dir_only = True
 
 
+############################
+# sphinx-llm configuration #
+############################
+
+# This description is included in llms.txt to provide some initial context for your
+# product docs.
+# TODO: Add a description in the form "This is the documentation for <product name>,
+# <first sentence of home page>".
+llms_txt_description = textwrap.dedent(
+    """\
+    This is the documentation for the Sphinx Starter Pack, a template repository
+    that helps you set up, build, and publish Sphinx documentation.
+    """
+)
+
+# The base URL for references built by sphinx-markdown-builder.
+if os.environ.get("READTHEDOCS"):
+    markdown_http_base = html_baseurl
+
 ###########################
 # Link checker exceptions #
 ###########################
@@ -246,7 +261,7 @@
     "https://example.com",
     # SourceForge domains often block linkcheck
     r"https://.*\.sourceforge\.(net|io)/.*",
-    ]
+]
 
 
 # A regex list of URLs where anchors are ignored by 'make linkcheck'
@@ -287,6 +302,7 @@
     "sphinx_config_options",
     "sphinx_contributor_listing",
     "sphinx_filtered_toctree",
+    "sphinx_llm.txt",
     "sphinx_related_links",
     "sphinx_roles",
     "sphinx_terminal",
@@ -378,8 +394,8 @@
 # If the user has a reuse/substitutions.yaml file, load from there.
 # Otherwise, use the manual definitions below.
 
-if os.path.exists('./reuse/substitutions.yaml'):
-    with open('./reuse/substitutions.yaml', 'r') as fd:
+if os.path.exists("./reuse/substitutions.yaml"):
+    with open("./reuse/substitutions.yaml", "r") as fd:
         myst_substitutions = yaml.safe_load(fd.read())
 else:
     myst_substitutions = {
@@ -391,5 +407,8 @@
 # Add configuration for intersphinx mapping
 # Map only the Sphinx documentation sets that you need to link to from your docs set.
 intersphinx_mapping = {
-    'sphinxcontrib-mermaid': ('https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest', None)
+    "sphinxcontrib-mermaid": (
+        "https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest",
+        None,
+    )
 }

docs/how-to/contributing-myst.md

@@ -1,4 +1,7 @@
 ---
+myst:
+  html_meta:
+    description: How to contribute code, documentation, and tests to the Starter Pack.
 orphan: true
 ---
 

docs/how-to/contributing.rst

@@ -1,5 +1,5 @@
 .. meta::
-   :description: How to contribute to the documentation project with code, writing, or testing.
+    :description: How to contribute code, documentation, and tests to the Starter Pack.
 
 :orphan:
 

docs/how-to/run-documentation-checks.rst

@@ -1,3 +1,6 @@
+.. meta::
+    :description: How to verify your documentation's spelling, links, and language with built-in checks.
+
 .. _run-documentation-checks :
 
 Run documentation checks

docs/reference/default-extensions.rst

@@ -62,6 +62,9 @@ These extensions are enabled in the Starter Pack by default.
 ``sphinx_last_updated_by_git``
    Fetches and displays the accurate 'last updated' date for pages by reading Git commit metadata.
 
+``sphinx_llm.txt``
+   Generates Markdown artifacts that improve readability for LLMs.
+
 ``sphinx_related_links``
    Generates and injects a list of related links into documentation pages.
 

docs/reference/github-workflows.rst

@@ -1,3 +1,6 @@
+.. meta::
+    :description: Reference for the built-in GitHub workflows that check your documentation's spelling, links, and language.
+
 .. _github-workflows:
 
 GitHub workflows

docs/reference/myst-syntax.md

@@ -2,7 +2,7 @@
 relatedlinks: https://github.com/canonical/canonical-sphinx-extensions, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en)
 myst:
   html_meta:
-    description: MyST Markdown syntax for use in Starter Pack projects, including headings, links, code blocks, directives, and reusable content patterns.
+    description: Reference for the MyST syntax conventions used by Canonical.
   substitutions:
     advanced_reuse_key: "This is a substitution that includes a code block:
                        ```

docs/reference/rst-syntax.rst

@@ -1,5 +1,5 @@
 .. meta::
-  :description: reStructuredText syntax for use in Starter Pack projects, including headings, links, code blocks, and tables.
+    :description: Reference for the reStructuredText syntax conventions used by Canonical.
 
 :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en)
 

docs/requirements.txt

@@ -27,6 +27,7 @@ packaging~=26.1
 sphinxcontrib-svg2pdfconverter[CairoSVG]~=2.1
 sphinx-last-updated-by-git~=0.3
 sphinx-sitemap~=2.9
+sphinx-llm~=0.4
 
 # Vale dependencies
 rst2html