diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index d7cbd1c..e1575ee 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -5,6 +5,7 @@ Canonical('s)? Charmcraft cjk cryptographically +discoverability dvipng fonts freefont @@ -70,6 +71,7 @@ GitHub Sphinx URL PR +PRs Read the Docs Spread landscape 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/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/index.rst b/docs/index.rst index 597fc12..9c8bb03 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,50 +1,189 @@ +.. _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 ` + - .. grid-item-card:: Get started - :link: /set-up-a-new-project - :link-type: doc +Content quality +~~~~~~~~~~~~~~~ - Set up the Sphinx Stack in your project for the first time. +Check your prose, links, and documented commands, run those checks automatically on +every change, and diagnose failures when they occur. - .. grid-item-card:: How-to guides - :link: /how-to/index - :link-type: doc +.. domain:: - **Step-by-step guides** - learn key operations and customisation. + .. slice:: Check your content -.. grid:: 1 1 2 2 + :doc:`Documentation checks ` + :doc:`Testing documented commands with Spread ` - .. grid-item-card:: Reference - :link: /reference/index - :link-type: doc + .. slice:: Continuous integration - **Technical information** - review the automatic checks and Sphinx capabilities. + :doc:`GitHub workflows ` + :doc:`Bridging project and docs builds ` - .. grid-item-card:: Explanation - :link: /explanation/index - :link-type: doc - **Concepts** - understand the design and architecture of the Sphinx Stack. +Lifecycle management +~~~~~~~~~~~~~~~~~~~~~ + +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:: Troubleshooting + + :doc:`Build errors ` + :doc:`Local deployment issues ` + :doc:`Runtime errors ` + :doc:`Read the Docs failures ` + + +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:`Contribute to documentation ` +* :ref:`Contribute to development ` + +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:: 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 ========= 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