Extension for Ansible redirects

.github/workflows/build-package-docs.yaml

@@ -9,37 +9,36 @@ name: Build and deploy docs
       repository-owner:
         description: GitHub account or org that owns the repository
         type: string
-        required: true
         default: ansible
       repository-name:
         description: Name of the GitHub repository
         type: string
-        required: true
         default: ansible-documentation
       repository-branch:
         description: Branch, tag, or commit SHA
         type: string
-        required: true
         default: devel
       ansible-package-version:
         description: Ansible community package version
         type: choice
-        required: true
         default: devel
         options:
         - devel
         - '12'
         - '11'
         - '10'
         - '9'
+      generate-redirects:
+        description: Generate page redirects
+        type: boolean
+        default: true
       deploy:
         description: Deploy the build
         type: boolean
-        required: true
+        default: false
       deployment-environment:
         description: Deployment environment
         type: choice
-        required: true
         default: test
         options:
         - production
@@ -54,6 +53,9 @@ jobs:
       repository-name:  ${{ github.event.inputs.repository-name || 'ansible-documentation' }}
       repository-branch: ${{ github.event.inputs.repository-branch || 'devel' }}
       ansible-package-version: ${{ github.event.inputs.ansible-package-version || 'devel' }}
+      generate-redirects: >-
+        ${{ github.event_name == 'workflow_dispatch'
+        && github.event.inputs.generate-redirects == 'true' }}
     secrets:
       DOCS_BOT_TOKEN: ${{ secrets.DOCS_BOT_TOKEN }}
 

.github/workflows/reusable-build-docs.yaml

@@ -7,23 +7,23 @@ name: Build docs
       repository-owner:
         description: GitHub account or org that owns the repository
         type: string
-        required: false
         default: ansible
       repository-name:
         description: Name of the GitHub repository
         type: string
-        required: false
         default: ansible-documentation
       repository-branch:
         description: Branch, tag, or commit SHA
         type: string
-        required: false
         default: devel
       ansible-package-version:
         type: string
         description: Ansible community package version
-        required: false
         default: devel
+      generate-redirects:
+        description: Generate page redirects
+        type: boolean
+        default: true
     secrets:
       DOCS_BOT_TOKEN:
         required: true
@@ -69,7 +69,9 @@ jobs:
 
     - name: Build the Ansible community package docs
       run: >-
-        make webdocs ANSIBLE_VERSION="${{
+        make webdocs ${{
+          inputs.generate-redirects && 'EXTRA_TAGS="-t redirects"' || ''
+        }} ANSIBLE_VERSION="${{
           env.PACKAGE_VERSION != 'devel' && env.PACKAGE_VERSION || ''
         }}"
       working-directory: build-directory/docs/docsite

.github/workflows/reusable-deploy-docs.yaml

@@ -7,22 +7,18 @@ name: Deploy docs
       repository-owner:
         description: GitHub account or org that owns the repository
         type: string
-        required: false
         default: ansible
       repository-branch:
         description: Branch, tag, or commit SHA
         type: string
-        required: false
         default: devel
       ansible-package-version:
         type: string
         description: Ansible community package version
-        required: false
         default: devel
       deployment-environment:
         description: Deployment environment
         type: string
-        required: false
         default: test
     secrets:
       DEPLOY_DOC_BUILD:

docs/docsite/Makefile.sphinx

@@ -2,10 +2,11 @@
 #
 
 # You can set these variables from the command line.
+EXTRA_TAGS    ?=
 DOCS_VARIANTS ?=
 SPHINXCONFDIR = rst
 LANGOPTS      ?=
-SPHINXOPTS    ?= -j $(CPUS) -n -w rst_warnings -c "$(SPHINXCONFDIR)" $(DOCS_VARIANTS) $(LANGOPTS)
+SPHINXOPTS    ?= -j $(CPUS) -n -w rst_warnings -c "$(SPHINXCONFDIR)" $(DOCS_VARIANTS) $(EXTRA_TAGS) $(LANGOPTS)
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = sdfsdf
 SOURCEDIR     = rst

docs/docsite/rst/conf.py

@@ -18,6 +18,12 @@
 
 import sys
 import os
+import tomllib
+from pathlib import Path
+
+from sphinx.application import Sphinx
+
+DOCS_ROOT_DIR = Path(__file__).parent.resolve()
 
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
@@ -372,7 +378,7 @@
 autoclass_content = 'both'
 
 # Note:  Our strategy for intersphinx mappings is to have the upstream build location as the
-# canonical source. 
+# canonical source.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/2/', None),
     'python3': ('https://docs.python.org/3/', None),
@@ -386,3 +392,20 @@
 ]
 linkcheck_workers = 25
 # linkcheck_anchors = False
+
+# Generate redirects for pages when building on Read The Docs
+def setup(app: Sphinx) -> dict[str, bool | str]:
+
+    if 'redirects' in app.tags:
+
+        redirects_config_path = DOCS_ROOT_DIR.parent / "declarative-configs" / "ansible_redirects.toml"
+        redirects = tomllib.loads(redirects_config_path.read_text())
+
+        app.config.redirects = redirects
+        app.setup_extension('sphinx_reredirects') # redirect pages that have been restructured or removed
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+        "version": app.config.release,
+    }

tests/requirements.in

@@ -9,6 +9,7 @@ sphinx
 sphinx-intl # translation utility used by docs/docsite/Makefile
 sphinx-notfound-page # extension used for the custom 404 page (cowsay)
 sphinx-ansible-theme # extension used for the custom docs theme
+sphinx-reredirects # extension to create redirects for moved pages
 sphinx-rtd-theme
 rstcheck
 yamllint

tests/requirements.txt

@@ -164,6 +164,7 @@ sphinx==7.2.5
     #   sphinx-copybutton
     #   sphinx-intl
     #   sphinx-notfound-page
+    #   sphinx-reredirects
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
 sphinx-ansible-theme==0.10.3
@@ -174,6 +175,8 @@ sphinx-intl==2.3.1
     # via -r tests/requirements.in
 sphinx-notfound-page==1.1.0
     # via -r tests/requirements.in
+sphinx-reredirects==0.1.5
+    # via -r tests/requirements.in
 sphinx-rtd-theme==3.0.2
     # via
     #   -c tests/constraints.in