From a6f208ef0e673a48a9fe67e30f4b15cb6607e8be Mon Sep 17 00:00:00 2001 From: asanvaq Date: Fri, 18 Sep 2026 12:56:17 +0200 Subject: [PATCH 1/6] feat: add sphinx-structured-toc extension --- docs/conf.py | 1 + docs/requirements.txt | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index f809268..70d13f3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -190,6 +190,7 @@ "sphinx_last_updated_by_git", "sphinx.ext.intersphinx", "sphinx_sitemap", + "sphinx_structured_toc", ] # Excludes files or directories from processing diff --git a/docs/requirements.txt b/docs/requirements.txt index 69c0782..065a9ab 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -18,6 +18,7 @@ sphinx-contributor-listing~=0.1 sphinx-filtered-toctree~=0.1 sphinx-related-links~=0.1 sphinx-roles~=0.1 +sphinx-structured-toc~=0.2 sphinx-terminal~=1.0 sphinx-ubuntu-images~=0.1 sphinx-youtube-links~=0.1 From 843d476b2cedf5c5f836ba6baceafa3bf0259eef Mon Sep 17 00:00:00 2001 From: asanvaq Date: Fri, 18 Sep 2026 12:56:56 +0200 Subject: [PATCH 2/6] feat: add or fix page labels --- docs/how-to/run-documentation-checks.rst | 2 +- docs/reference/index.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/how-to/run-documentation-checks.rst b/docs/how-to/run-documentation-checks.rst index 542d5a2..17b8c48 100644 --- a/docs/how-to/run-documentation-checks.rst +++ b/docs/how-to/run-documentation-checks.rst @@ -1,7 +1,7 @@ .. meta:: :description: How to verify your documentation's spelling, links, and language with built-in checks. -.. _run-documentation-checks : +.. _run-documentation-checks: Run documentation checks ======================== diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 85ce2ed..190d3f1 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,3 +1,5 @@ +.. _reference: + Reference ========= From 384464f5010ebbc5c4e01538c4fce704a9026dc2 Mon Sep 17 00:00:00 2001 From: asanvaq Date: Fri, 18 Sep 2026 12:59:53 +0200 Subject: [PATCH 3/6] docs: update to new homepage model and apply structured-toctree --- docs/index.rst | 186 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 161 insertions(+), 25 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 597fc12..daf14b6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,50 +1,186 @@ +.. _sphinx-stack: + Sphinx Stack documentation ========================== -The Sphinx Stack helps you set up, build, and publish documentation with Sphinx. +**The Sphinx Stack is a template Sphinx project for Canonical documentation.** It +provides a Canonical standardized structured content layout, a Canonical-branded theme, +and a curated set of Sphinx extensions. + +**The Sphinx Stack bundles the tools and configuration needed to build and publish Sphinx +documentation.** It includes the ``canonical-sphinx`` extension for consistent styling, +supports both reStructuredText and Markdown source files, and provides GitHub Actions +workflows for automated spelling, link, and inclusive language checks. -It contains common styling and configuration through the `Canonical Sphinx -`__ extension, supports both |RST| and -Markdown, and includes automatic documentation checks. +**This documentation covers information about how the Sphinx Stack works and how to +deploy and customize it for any documentation project.** It also covers optional +extensions for diagrams, API specifications, interactive tables, and PDF output. + +**The documentation is for Canonical contributors and engineers adding or maintaining +documentation in a Sphinx Stack project.** It assumes familiarity with command-line +tools and version control, but does not require prior Sphinx experience. In this documentation --------------------- -.. grid:: 1 1 2 2 +Getting started +~~~~~~~~~~~~~~~ + +Create, configure, build and publish your documentation. + +.. domain:: + + .. slice:: First project + + :doc:`Set up a new project ` + :doc:`Configure your project ` + + .. slice:: Build and publish + + :doc:`Build and preview ` + :doc:`Publishing on Read the Docs ` + + +Content features +~~~~~~~~~~~~~~~~~ + +Write your pages in either supported markup language, enrich them with diagrams and +generated reference material, and control how they are rendered and found. + +.. domain:: + + .. slice:: Syntax guides + + :doc:`MyST for Markdown ` + :doc:`reStructuredText ` + + .. slice:: Diagrams and tables + + :doc:`Mermaid diagrams ` + :doc:`Interactive tables ` + + .. slice:: API documentation + + :doc:`API docs from Python docstrings ` + :doc:`OpenAPI specifications ` + + .. slice:: Customizing output + + :doc:`Custom HTML templates ` + :doc:`PDF output ` + :doc:`Page-specific configuration ` + + .. slice:: Stable and outbound links + + :doc:`Redirects for moved pages ` + :doc:`Intersphinx links to other doc sets ` + + .. slice:: Discoverability + + :doc:`Manage sitemaps ` + :doc:`Enable Google Analytics ` + + +Content quality +~~~~~~~~~~~~~~~ - .. grid-item-card:: Get started - :link: /set-up-a-new-project - :link-type: doc +Check your prose, links, and documented commands, run those checks automatically on +every change, and diagnose failures when they occur. - Set up the Sphinx Stack in your project for the first time. +.. domain:: - .. grid-item-card:: How-to guides - :link: /how-to/index - :link-type: doc + .. slice:: Check your content - **Step-by-step guides** - learn key operations and customisation. + :doc:`Documentation checks ` + :doc:`Testing documented commands with Spread ` -.. grid:: 1 1 2 2 + .. slice:: Continuous integration - .. grid-item-card:: Reference - :link: /reference/index - :link-type: doc + :doc:`GitHub workflows ` + :doc:`Bridging project and docs builds ` - **Technical information** - review the automatic checks and Sphinx capabilities. - .. grid-item-card:: Explanation - :link: /explanation/index - :link-type: doc +Lifecycle management +~~~~~~~~~~~~~~~~~~~~~ - **Concepts** - understand the design and architecture of the Sphinx Stack. +Upgrade an existing documentation set onto a current version of the Sphinx Stack. + +.. domain:: + + .. slice:: Upgrade paths + + :doc:`Upgrade from a new version ` + :doc:`Upgrade from the legacy version ` + + .. slice:: Fix issues + + :doc:`Troubleshooting ` + + +How the stack works +~~~~~~~~~~~~~~~~~~~~ + +Understand what the stack ships with and how it assembles your source files into a +finished site. + +.. domain:: + + .. slice:: Core components + + :doc:`Sphinx Stack structure ` + :doc:`The build process ` + + .. slice:: Default settings + + :doc:`Default Sphinx extensions ` + :doc:`Default Sphinx configuration ` + :doc:`Sitemaps ` + + +How this documentation is organized +------------------------------------- + +This documentation uses the `Diátaxis documentation structure `_. + +* :ref:`Set up a new project ` walks through copying the Sphinx + Stack template, removing unneeded files, and performing the required initial + configuration before the first build. +* :ref:`How-to guides ` cover specific tasks: building locally, running + documentation checks, publishing on Read the Docs, updating the stack, and enabling + optional extensions. +* :ref:`Reference ` provides the list of default Sphinx extensions, GitHub + workflow definitions, and the reST and MyST syntax guide. +* :ref:`Explanation ` describes the architecture of the Sphinx Stack, + covering its core components (Sphinx, Python, extensions), the Make-based build + system, and sitemap generation. Project and community ----------------------- +----------------------- + +The Sphinx Stack is a Canonical open source project that forms part of the tooling +supporting documentation across Ubuntu and other Canonical offerings. + + +Get involved +~~~~~~~~~~~~ + +* `Sphinx Stack repository `__ +* `Issue tracker `__ +* :ref:`Contribution guide ` + + +Releases +~~~~~~~~ + +* :ref:`Release notes ` + + +Governance and policies +~~~~~~~~~~~~~~~~~~~~~~~~ -The Sphinx Stack is an open source project that warmly welcomes community contributions, -suggestions, fixes and constructive feedback. +* `Code of conduct `__ .. toctree:: From ce54c1c9bb3c47ce13ac7f0d2e1cf4e204a274d2 Mon Sep 17 00:00:00 2001 From: asanvaq Date: Fri, 18 Sep 2026 13:08:07 +0200 Subject: [PATCH 4/6] docs: add both contribution guides --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index daf14b6..0f3f300 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -168,8 +168,8 @@ Get involved * `Sphinx Stack repository `__ * `Issue tracker `__ -* :ref:`Contribution guide ` - +* :ref:`Contribute to documentation ` +* :ref:`Contribute to development ` Releases ~~~~~~~~ From ae487670293fc7daaf7fd8c74cb825fa5e32209f Mon Sep 17 00:00:00 2001 From: asanvaq Date: Fri, 18 Sep 2026 13:08:34 +0200 Subject: [PATCH 5/6] fix: add words to custom_wordlist --- docs/.custom_wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 11aec07..5234ac3 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -5,6 +5,7 @@ Canonical('s)? Charmcraft cjk cryptographically +discoverability dvipng fonts freefont @@ -69,6 +70,7 @@ GitHub Sphinx URL PR +PRs Read the Docs Spread landscape From 5d4f22a69ef6e52bf70adf88d790a0f3365197f8 Mon Sep 17 00:00:00 2001 From: asanvaq Date: Fri, 18 Sep 2026 13:32:05 +0200 Subject: [PATCH 6/6] docs: add troubleshooting pages --- docs/index.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 0f3f300..9c8bb03 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -113,9 +113,12 @@ Upgrade an existing documentation set onto a current version of the Sphinx Stack :doc:`Upgrade from a new version ` :doc:`Upgrade from the legacy version ` - .. slice:: Fix issues + .. slice:: Troubleshooting - :doc:`Troubleshooting ` + :doc:`Build errors ` + :doc:`Local deployment issues ` + :doc:`Runtime errors ` + :doc:`Read the Docs failures ` How the stack works