docs: describe extension support

docs/how-to/configure-your-project.rst

@@ -138,11 +138,18 @@ the selection in the  ``docs/conf.py`` file.
 The canonical-sphinx extension is required for the Sphinx Stack and provides the
 Furo-based theme and custom templates.
 
-To add new extensions needed for your documentation set, add them to the ``extensions`` parameter in ``docs/conf.py``.
-
-.. note::
-
-   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.
+To add an extension to your documentation set, add its Python package to the
+``docs/requirements.txt`` file and add the module to the ``extensions`` list in the
+``docs/conf.py`` file.
+
+.. admonition:: Extension support
+    :class: note
+
+    The only extensions formally supported by the Sphinx Stack are those included in its
+    `default requirements.txt file
+    <https://github.com/canonical/sphinx-stack/blob/main/docs/requirements.txt>`__. If
+    you add any extensions to this list, it's your responsibility to ensure that they're
+    compatible with the rest of the Sphinx Stack.
 
 
 Add page-specific configuration

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,24 +114,25 @@ 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
 ~~~~~~~~~~~~
 
-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.
 
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 #. 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`