Add a [sphinx.redirects] table to documenteer.toml

This also updates documenteer's own docs to use this feature.

changelog.d/20240502_175753_jsick_DM_44193.md

@@ -0,0 +1,3 @@
+### New features
+
+- Added a [sphinx.redirects] table to `documenteer.toml`. This provides support for configuring page redirects from the TOML configuratin. Redirects are useful if pages move because of a content re-organization. This feature is based on [sphinx-rediraffe](https://github.com/wpilibsuite/sphinxext-rediraffe).

docs/conf.py

@@ -1,13 +1,3 @@
 # See the documenteer.toml for overrides of the Rubin user guide presets
 
-from documenteer.conf.guide import *
-
-rediraffe_redirects = {
-    "pipelines/build-overview.rst": "guides/pipelines/build-overview.rst",
-    "pipelines/configuration.rst": "guides/pipelines/configuration.rst",
-    "pipelines/cpp-api-linking.rst": "guides/pipelines/cpp-api-linking.rst",
-    "pipelines/index.rst": "guides/pipelines/index.rst",
-    "pipelines/install.rst": "guides/pipelines/install.rst",
-    "pipelines/package-docs-cli.rst": "guides/pipelines/package-docs-cli.rst",
-    "pipelines/stack-docs-cli.rst": "guides/pipelines/stack-docs-cli.rst",
-}
+from documenteer.conf.guide import *  # noqa: F403

docs/documenteer.toml

@@ -44,3 +44,12 @@ technote = "https://technote.lsst.io/"
 ignore = [
     "https://mermaid-js.github.io"
 ]
+
+[sphinx.redirects]
+"pipelines/build-overview.rst" = "guides/pipelines/build-overview.rst"
+"pipelines/configuration.rst" = "guides/pipelines/configuration.rst"
+"pipelines/cpp-api-linking.rst" = "guides/pipelines/cpp-api-linking.rst"
+"pipelines/index.rst" = "guides/pipelines/index.rst"
+"pipelines/install.rst" = "guides/pipelines/install.rst"
+"pipelines/package-docs-cli.rst" = "guides/pipelines/package-docs-cli.rst"
+"pipelines/stack-docs-cli.rst" = "guides/pipelines/stack-docs-cli.rst"

docs/guides/index.rst

@@ -26,6 +26,7 @@ Documenteer provides a configuration profile for creating branded user guides wi
    pyproject-configuration
    openapi
    rst-epilog
+   page-redirects
    extend-conf-py
 
 .. toctree::

docs/guides/page-redirects.rst

@@ -0,0 +1,42 @@
+###########################################
+Redirecting pages when reorganizing content
+###########################################
+
+As a documentation site grows, its natural for content to need to move.
+If pages are moved or renamed, you should create a redirect from the old page path to the new one so that users won't be orphaned by out-of-date links and bookmarks.
+Documenteer supports this with the :ref:`guide-sphinx-redirects` table in the :file:`documenteer.toml` configuration file.
+
+Adding a page redirect in documenteer.toml
+==========================================
+
+As an example, consider the page at :file:`old-page.rst` has moved to :file:`some-dir/new-page.rst`.
+To create a redirect from the old page to the new one, add the following to the :file:`documenteer.toml` file:
+
+.. code-block:: toml
+   :caption: documenteer.toml
+
+   [sphinx.redirects]
+   "old-page.rst" = "some-dir/new-page.rst"
+
+These paths are relative to the documentation project's root directory (where :file:`conf.py` and :guide:`documenteer.toml` are located) and include the file extension (e.g., :file:`.rst` or :file:`.md`).
+
+The table accepts an arbitrary number of redirects:
+
+.. code-block:: toml
+   :captin: documenteer.toml
+
+   [sphinx.redirects]
+   "old-page.rst" = "some-dir/new-page.rst"
+   "foo.rst" = "bar.rst"
+
+Redirects for deleted pages
+===========================
+
+Besides pages that have been moved, you can use this feature for pages that have been deleted.
+Choose an existing path that is most relevant to the deleted page and redirect it to the new location.
+
+.. code-block:: toml
+   :caption: documenteer.toml
+
+   [sphinx.redirects]
+   "deleted-page.rst" = "index.rst"

docs/guides/toml-reference.rst

@@ -372,10 +372,27 @@ The default value is ``api``, which is a good standard for Python projects with
 If the Python API is oriented towards contributors, such as in an application or service, you can change the default:
 
 .. code-block:: toml
+   :caption: documenteer.toml
 
    [sphinx]
    python_api_dir = "dev/api/contents"
 
+.. _guide-sphinx-redirects:
+
+[sphinx.redirects]
+==================
+
+|optional|
+
+A table of paths to redirect to other paths. Use this setting to redirect old page locations to the new locations when a documentation site is reorganized.
+
+.. code-block:: toml
+   :caption: documenteer.toml
+
+   [sphinx.redirects]
+   "old/path" = "new/path"
+   "old/path2" = "new/path2"
+
 [sphinx.theme]
 ==============
 

src/documenteer/conf/_toml.py

@@ -276,6 +276,14 @@ class SphinxModel(BaseModel):
 
     linkcheck: LinkCheckModel = Field(default_factory=lambda: LinkCheckModel())
 
+    redirects: Dict[str, str] = Field(
+        description=(
+            "Mapping of paths to redirect to other paths. These redirects "
+            "are implemented with sphinx-rediraffe."
+        ),
+        default_factory=dict,
+    )
+
 
 class ConfigRoot(BaseModel):
     """The root model for a documenteer.toml configuration file."""
@@ -409,6 +417,14 @@ def rst_epilog(self) -> str:
         else:
             return self.rst_epilog_path.read_text()
 
+    @property
+    def redirects(self) -> Dict[str, str]:
+        """Redirects defined in the [sphinx.redirects] TOML configuration."""
+        if self.conf.sphinx:
+            return self.conf.sphinx.redirects
+        else:
+            return dict()
+
     def _get_pyproject_metadata(self, package_name: str) -> Message:
         if sys.version_info >= (3, 10) or sys.version_info < (3, 8):
             pkg_metadata = cast(Message, metadata(package_name))

src/documenteer/conf/guide.py

@@ -456,4 +456,4 @@
 # #REDIRECTS Sphinx-rediraffe support
 # https://sphinxext-rediraffe.readthedocs.io/en/latest/
 # ============================================================================
-rediraffe_redirects: dict[str, str] = {}
+rediraffe_redirects: dict[str, str] = _conf.redirects