Implement a redirect extension and policy

[aputtu]

Documentation Linking Strategy and Requirements

• Document ID: DOC-LINK-REQ-1.0
• Date: August 13, 2025
• Status: Draft

1. Introduction

The purpose of this document is to define the requirements for a robust and maintainable linking strategy for the project's Sphinx documentation. A stable linking strategy is critical for providing a positive User Experience (UX), maintaining Search Engine Optimization (SEO) value, and reducing long-term maintenance overhead. This specification covers both internal links (within the documentation) and external inbound links (from outside websites).

2. Scope

These requirements apply to all documentation generated by the Sphinx build system. The primary goal is to ensure that links remain functional even as the documentation evolves and its content is rearranged.

---

3. Core Requirements

3.1. Internal Linking (Cross-References)

• Requirement 1.1: Location-Independent Linking
  • Description: Links between pages within the documentation must not break when the target content (e.g., a section, figure, or table) is moved to a different source file.
  • Rationale: Documentation is frequently refactored. A manual process for updating links is error-prone and inefficient.
  • Acceptance Criteria: The linking mechanism must use stable, logical identifiers associated with content, not hardcoded file paths. The build system must automatically resolve these identifiers to the correct URL, regardless of the target content's location within the project.

3.2. External Inbound Linking

• Requirement 2.1: URL Persistence and Redirection

  • Description: A mechanism must be in place to handle inbound links from external sites that point to a URL that no longer exists due to file renaming or relocation. Users accessing a legacy URL shall be automatically redirected to the new, canonical URL.
  • Rationale: To prevent "link rot," which damages user trust and SEO ranking. External stakeholders cannot be expected to update their links.
  • Acceptance Criteria: An HTTP request to a legacy URL returns a permanent redirect (HTTP 301) to the current URL. The process is seamless for the end-user.

• Requirement 2.2: Maintainable Redirect Management

  • Description: The process for managing URL redirects should be integrated into the documentation workflow and version-controlled with the source code.
  • Rationale: Relying on separate server administration for redirects creates friction and is not scalable for documentation teams. Managing redirects as code (e.g., in conf.py) keeps the responsibility within the project.
  • Acceptance Criteria: A documentation author can define a redirect by adding an entry to a project configuration file. The build process must then generate the necessary redirection logic (e.g., via HTML meta refresh pages or other means), without requiring manual server configuration.

---

4. Glossary

• Internal Link: A hyperlink from one page within the documentation set to another page within the same set.
• External Inbound Link: A hyperlink from a separate, external website that points to a page within our documentation.
• Link Rot: The tendency for hyperlinks to become broken over time as their target content is moved or deleted.
• Stable Identifier: A unique, persistent name assigned to a piece of content that is used for internal linking.

[aputtu]

Possible Extension for handling External Inbound Linking: sphinx-redirects

URL: https://pypi.org/project/sphinx-reredirects/

For Sphinx projects, the easiest and most common way to handle this is with an extension like sphinx-reredirects. This lets you manage redirects directly within your Sphinx project.

How It Works

1. You install the extension: pip install sphinx-reredirects
2. You enable it in your conf.py file and add a simple configuration that maps old pages to new pages.
3. When you build your documentation, the extension automatically creates simple HTML files at the old locations. These files contain code that instantly and automatically sends the user's browser to the new page.

Example Scenario

Let's say you move your dessert recipes from a single page into a folder.

• Old URL: .../recipes/desserts.html
• New URL: .../recipes/desserts/apple_pie.html

You would add this to your conf.py file:

# In your conf.py

extensions = [
    'sphinx_reredirects',
]

redirects = {
    # "old-page.html": "new-page.html"
    "recipes/desserts.html": "desserts/apple_pie.html",
}

Now, when someone from randomdomain.com clicks the old link, they will land on a hidden page at .../recipes/desserts.html which immediately forwards them to the new .../desserts/apple_pie.html page. The user might see a quick flash, but otherwise, the experience is seamless.

[aputtu]

Internal Linking (Cross-refences)

Simply make sure to use Sphinx's labels (must be unique across project) and then have the :ref: role refer to them.

Creating the Label
Say in installation.rst, use label on top (we do this, we should have a test to verify we always do so).

.. _install-guide:

Installation Guide
===============

Here are the steps to install the software...

Creating the Referene
From other pages referring to the Installation page, use role:

If you continue to have issues, you may need to :ref:`re-install using the official guide <install-guide>`.

For a quick link, see the :ref:`install-guide`.