Sphinx Reredirects

Warnings

• breaking Version 1.0.0 introduced stricter Python and Sphinx version requirements. It now requires Python >= 3.11 and Sphinx >= 7.4.
  Fix: Ensure your environment meets Python >= 3.11 and Sphinx >= 7.4. Upgrade Sphinx using `pip install -U sphinx` if necessary.
• gotcha The extension only supports HTML-based builders (like `html` and `dirhtml`). It performs no action when building to other outputs (e.g., `linkcheck`, `latex`).
  Fix: Be aware that redirects are only generated for HTML output. This is by design, as meta refresh redirects are an HTML-specific mechanism.
• gotcha If a source document specified in the `redirects` configuration exists, its generated HTML file will be *overwritten* by the redirect HTML. This is intentional to ensure the redirect takes precedence.
  Fix: Plan your redirects carefully. If you intend to redirect an *existing* document, understand that its original content will no longer be accessible at that path in the built output.
• gotcha The Sphinx `linkcheck` builder does not currently support checking redirects to other pages *within the same documentation project* when using `sphinx-reredirects`. It only checks redirects to external URLs.
  Fix: Manually verify internal redirects or use other tools. The extension cooperates with `linkcheck` for external redirects.
• deprecated In versions prior to 0.1.6, URL fragments (e.g., `#section`) were not preserved during redirects, leading to loss of specific link targets.
  Fix: Upgrade to `sphinx-reredirects` version 0.1.6 or newer, as this feature was added and is now the default behavior. For older versions, a custom HTML template was required.

Install

• pip install sphinx-reredirects Install latest version

Imports

• 'sphinx_reredirects'

  extensions = ['sphinx_reredirects', ...]

  The extension is enabled by adding its string name to the 'extensions' list in conf.py, not as a direct Python import.

Quickstart

To use sphinx-reredirects, first ensure it's added to your `extensions` list in `conf.py`. Then, define the `redirects` dictionary in the same file, mapping old Sphinx document names (without extensions) to their new relative or absolute URL targets. Wildcards and placeholders are supported.

# In your project's conf.py file:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx_reredirects'
]

# Define your redirects. Keys are old docnames, values are new URLs.
# Docnames are paths without file extensions (e.g., 'old_chapter/intro' for 'old_chapter/intro.rst').
# Targets can be relative to the project root or absolute URLs.
redirects = {
    "old-page": "new-page.html",
    "removed-feature": "https://external.com/docs/new-home",
    "legacy/*": "current_docs/$source.html" # Wildcard example
}

# To build the documentation and apply redirects:
# sphinx-build -M html source build