Extension for Ansible redirects (#2418)

oraNod · webknjaz · web-flow · commit 6d4338a9234b · 2025-06-03T20:43:10.000+01:00
* add reredirects dependency

* update conf file to generate ansible redirects

* add extra tags to makefile

* define redirect rules in key value pairs

* update build workflows to generate redirects

* add redirect template for SEO purposes

---------

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) &lt;wk.cvs.github@sydorenko.org.ua&gt;
diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml
@@ -32,10 +32,15 @@ name: Build and deploy docs
         - '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
@@ -54,6 +59,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 }}
 
diff --git a/.github/workflows/reusable-build-docs.yaml b/.github/workflows/reusable-build-docs.yaml
@@ -24,6 +24,10 @@ name: Build docs
         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 +73,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
diff --git a/docs/docsite/.templates/redirect_template.html b/docs/docsite/.templates/redirect_template.html
@@ -0,0 +1 @@
+<html><head><meta name="robots" content="noindex"><noscript><meta http-equiv="refresh" content="0; url=${to_uri}" /></noscript><script>var target = "${to_uri}";if (window.location.hash) {window.location.replace(target + window.location.hash);} else {window.location.replace(target);}</script></head></html>
diff --git a/docs/docsite/Makefile.sphinx b/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
diff --git a/docs/docsite/declarative-configs/ansible_redirects.toml b/docs/docsite/declarative-configs/ansible_redirects.toml
diff --git a/docs/docsite/rst/conf.py b/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
@@ -376,7 +382,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),
@@ -390,3 +396,22 @@
 ]
 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())
+        redirect_template = DOCS_ROOT_DIR.parent / ".templates" / "redirect_template.html"
+
+        app.config.redirects = redirects
+        app.config.redirect_html_template_file = redirect_template
+        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,
+    }
diff --git a/tests/requirements.in b/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
diff --git a/tests/requirements.txt b/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.6
+    # via -r tests/requirements.in
 sphinx-rtd-theme==3.0.2
     # via
     #   -c tests/constraints.in

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+<html><head><meta name="robots" content="noindex"><noscript><meta http-equiv="refresh" content="0; url=${to_uri}" /></noscript><script>var target = "${to_uri}";if (window.location.hash) {window.location.replace(target + window.location.hash);} else {window.location.replace(target);}</script></head></html>`