From 047dd742921b456385bfdd737c0cf6bf84eb2bed Mon Sep 17 00:00:00 2001 From: shaloo <5890484+shaloo@users.noreply.github.com> Date: Fri, 19 Jun 2026 20:46:05 +0530 Subject: [PATCH 1/3] fix: #DOCPR-1799 add a note for limited support if using new extensions or customizations --- docs/how-to/configure-your-project.rst | 1 + .../legacy-sphinx-stack.rst | 21 ++++++++++--------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/how-to/configure-your-project.rst b/docs/how-to/configure-your-project.rst index 3d9a963..6527f9b 100644 --- a/docs/how-to/configure-your-project.rst +++ b/docs/how-to/configure-your-project.rst @@ -144,6 +144,7 @@ To add new extensions needed for your documentation set, add them to the ``exten If any additional extensions need specific Python packages, ensure they are installed alongside the other requirements by adding them to the ``docs/requirements.txt`` file. + The Sphinx Stack fully supports only the third-party extensions included in the Starter pack. Support is limited for extensions you add or customize in requirements.txt Add page-specific configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst b/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst index b7b3922..9427fa7 100644 --- a/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst +++ b/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst @@ -3,7 +3,7 @@ .. _update-legacy-sphinx-stack: -Update the legacy Sphinx Stack +Update the legacy Sphinx Stack ============================== This guide outlines the steps required to migrate a documentation project from the @@ -65,7 +65,7 @@ Set up a new project - ``.github/workflows/*`` #. Ensure the following files are moved to their original paths in the project. These files are defaulted to the repository root, but may have be changed upon project - needs: + needs: - ``.gitignore`` - ``.readthedocs.yml`` @@ -98,7 +98,7 @@ files, summarised in the following table: :header-rows: 1 * - Configuration file - - Pre-extension + - Pre-extension - Extension-based * - ``conf.py`` - Common configurations shared by all Sphinx Stack projects @@ -114,7 +114,7 @@ defaults are set for general configuration by inclusion of the ``canonical-sphin extension. Ensure that all the previous changes in the original ``custom_conf.py`` file are copied -to the new ``conf.py`` file. +to the new ``conf.py`` file. Dependencies @@ -123,6 +123,7 @@ Dependencies If your project requires additional extensions beyond the default list, add the extension list to the new project in ``docs/requirements.txt``. +The legacy Sphinx Stack fully supports only the third-party extensions included in the Starter pack. Support is limited for extensions you add or customize in requirements.txt Documentation source files ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -130,8 +131,8 @@ Documentation source files #. Copy all documentation source files from your original project to the new project, keeping their original structure. These file may include but are not limited to: - - ``.md`` - - ``.rst`` + - ``.md`` + - ``.rst`` - ``.txt`` - ``.json`` - images @@ -158,7 +159,7 @@ These resources are bundled with the extension and are no longer provided as sou files in the new Sphinx Stack. If you have customised any of these resources in the original project, you need to -manually migrate these changes to the new project. +manually migrate these changes to the new project. For example, if you added customised styling in the original ``.sphinx/_static/custom.css`` file, follow the steps: @@ -235,9 +236,9 @@ following list illustrates the changes in the directory structure after the migr │ ├── pa11y-ci.json # renamed to `pa11y.json` │ └── spellingcheck.yaml ├── metrics # removed - │ └── scripts - │ ├── build_metrics.sh - │ └── source_metrics.sh + │ └── scripts + │ ├── build_metrics.sh + │ └── source_metrics.sh ├── reuse # removed │ └── links.txt ├── .custom_wordlist.txt # moved to `docs/.custom_wordlist.txt` From 9a221a690a13eead8d42658cb01e95759981f945 Mon Sep 17 00:00:00 2001 From: shalz Date: Wed, 15 Jul 2026 15:16:48 +0530 Subject: [PATCH 2/3] Update docs/how-to/configure-your-project.rst Co-authored-by: Andreia --- docs/how-to/configure-your-project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/configure-your-project.rst b/docs/how-to/configure-your-project.rst index 6527f9b..47af075 100644 --- a/docs/how-to/configure-your-project.rst +++ b/docs/how-to/configure-your-project.rst @@ -144,7 +144,7 @@ To add new extensions needed for your documentation set, add them to the ``exten If any additional extensions need specific Python packages, ensure they are installed alongside the other requirements by adding them to the ``docs/requirements.txt`` file. - The Sphinx Stack fully supports only the third-party extensions included in the Starter pack. Support is limited for extensions you add or customize in requirements.txt + The only third-party extensions the Sphinx Stack fully supports are those included via the [canonical-sphinx extension bundle](https://github.com/canonical/canonical-sphinx). Add page-specific configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From dfd7b4566167ab80aa3895b11b5e91007772039d Mon Sep 17 00:00:00 2001 From: shalz Date: Tue, 21 Jul 2026 09:01:07 +0530 Subject: [PATCH 3/3] Update docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst Co-authored-by: JJ Coldiron --- docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst b/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst index 9427fa7..4ac00cb 100644 --- a/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst +++ b/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst @@ -120,10 +120,10 @@ to the new ``conf.py`` file. Dependencies ~~~~~~~~~~~~ -If your project requires additional extensions beyond the default list, add the -extension list to the new project in ``docs/requirements.txt``. +The Sphinx Stack supports a reasonable set of default extensions. If your project requires additional extensions, add them to the project's ``docs/requirements.txt`` file. -The legacy Sphinx Stack fully supports only the third-party extensions included in the Starter pack. Support is limited for extensions you add or customize in requirements.txt +It's your responsibility to ensure that extensions you add to this list are compatible with +the rest of the Sphinx Stack. Documentation source files ~~~~~~~~~~~~~~~~~~~~~~~~~~