From 584d15eb2a3247745608c141a6b04382d8dca7ea Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 2 May 2024 18:03:06 -0400 Subject: [PATCH] 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 | 3 ++ docs/conf.py | 12 +----- docs/documenteer.toml | 9 ++++ docs/guides/index.rst | 1 + docs/guides/page-redirects.rst | 42 +++++++++++++++++++ docs/guides/toml-reference.rst | 17 ++++++++ src/documenteer/conf/_toml.py | 16 +++++++ src/documenteer/conf/guide.py | 2 +- 8 files changed, 90 insertions(+), 12 deletions(-) create mode 100644 changelog.d/20240502_175753_jsick_DM_44193.md create mode 100644 docs/guides/page-redirects.rst diff --git a/changelog.d/20240502_175753_jsick_DM_44193.md b/changelog.d/20240502_175753_jsick_DM_44193.md new file mode 100644 index 00000000..ff4f2e08 --- /dev/null +++ b/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). diff --git a/docs/conf.py b/docs/conf.py index 8e08d986..9c4f776a 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/documenteer.toml b/docs/documenteer.toml index 5135df8a..31ed1690 100644 --- a/docs/documenteer.toml +++ b/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" diff --git a/docs/guides/index.rst b/docs/guides/index.rst index d122d424..e7a2a153 100644 --- a/docs/guides/index.rst +++ b/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:: diff --git a/docs/guides/page-redirects.rst b/docs/guides/page-redirects.rst new file mode 100644 index 00000000..9f2b4f6c --- /dev/null +++ b/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" diff --git a/docs/guides/toml-reference.rst b/docs/guides/toml-reference.rst index c582e822..52aaa20d 100644 --- a/docs/guides/toml-reference.rst +++ b/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] ============== diff --git a/src/documenteer/conf/_toml.py b/src/documenteer/conf/_toml.py index 15850a0a..e447ac2b 100644 --- a/src/documenteer/conf/_toml.py +++ b/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)) diff --git a/src/documenteer/conf/guide.py b/src/documenteer/conf/guide.py index f5d40e66..8bd0d69a 100644 --- a/src/documenteer/conf/guide.py +++ b/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