diff --git a/CHANGELOG.md b/CHANGELOG.md index 8dcb1d5e..1c6831f2 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 08e6477d..529c24a6 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -20,6 +20,7 @@ Kompare lang LaTeX latexmk +LLMs? Multipass npm otf @@ -27,6 +28,7 @@ plantuml PNG Pygments pymarkdown +pymarkdownlnt QEMU Rockcraft readthedocs diff --git a/docs/Makefile b/docs/Makefile index fa6d193e..07e7d4b9 100644 --- a/docs/Makefile +++ b/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 ?= . diff --git a/docs/conf.py b/docs/conf.py index 87a5d440..5a328587 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,5 +1,7 @@ import datetime import os +import textwrap + import yaml # Configuration for the Sphinx documentation builder. @@ -118,11 +120,9 @@ # 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 @@ -130,13 +130,10 @@ # "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 , +# ". +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, + ) } diff --git a/docs/how-to/contributing-myst.md b/docs/how-to/contributing-myst.md index f8707224..2efcd9c6 100644 --- a/docs/how-to/contributing-myst.md +++ b/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 --- diff --git a/docs/how-to/contributing.rst b/docs/how-to/contributing.rst index cc50b4e3..82f97354 100644 --- a/docs/how-to/contributing.rst +++ b/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: diff --git a/docs/how-to/run-documentation-checks.rst b/docs/how-to/run-documentation-checks.rst index 410d7f41..76cdbece 100644 --- a/docs/how-to/run-documentation-checks.rst +++ b/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 diff --git a/docs/reference/default-extensions.rst b/docs/reference/default-extensions.rst index 0ab8e58c..e19586fc 100644 --- a/docs/reference/default-extensions.rst +++ b/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. diff --git a/docs/reference/github-workflows.rst b/docs/reference/github-workflows.rst index 00e4a3e8..10ebea6f 100644 --- a/docs/reference/github-workflows.rst +++ b/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 diff --git a/docs/reference/myst-syntax.md b/docs/reference/myst-syntax.md index cbd63bc8..f352227d 100644 --- a/docs/reference/myst-syntax.md +++ b/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: ``` diff --git a/docs/reference/rst-syntax.rst b/docs/reference/rst-syntax.rst index 67ff1d14..9353991e 100644 --- a/docs/reference/rst-syntax.rst +++ b/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) diff --git a/docs/requirements.txt b/docs/requirements.txt index 0b2e2789..c8c0535c 100644 --- a/docs/requirements.txt +++ b/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