[PATCH v3] docs: directive `alias` for redirects

and several redirects for moved main arch pages

Problems:
- The documentation lacks hierarchy
- Relocating pages disrupts external links to
  the documentation and causes confusion for users

Benefits:
- Users can easily access relocated pages from external resources
- Using redirects frees up options for reorganizing the documentation

The solution:
- Introduced directive `alias` which declares previous path of
  a moved document as the argument.
- Redirects are implemented with Sphinx extension rediraffe_redirects.

Signed-off-by: Costa Shulyupin <[email protected]>

---

Changes:
- complete new implementation
---
 Documentation/arch/arc/index.rst        |  2 ++
 Documentation/arch/ia64/index.rst       |  2 ++
 Documentation/arch/index.rst            |  2 ++
 Documentation/arch/m68k/index.rst       |  2 ++
 Documentation/arch/nios2/index.rst      |  2 ++
 Documentation/arch/openrisc/index.rst   |  2 ++
 Documentation/arch/parisc/index.rst     |  2 ++
 Documentation/arch/sh/index.rst         |  2 ++
 Documentation/arch/sparc/index.rst      |  2 ++
 Documentation/arch/x86/index.rst        |  2 ++
 Documentation/arch/x86/x86_64/index.rst |  2 ++
 Documentation/arch/xtensa/index.rst     |  2 ++
 Documentation/conf.py                   |  9 +++++++
 Documentation/sphinx/alias.py           | 35 +++++++++++++++++++++++++
 Documentation/sphinx/requirements.txt   |  1 +
 15 files changed, 69 insertions(+)
 create mode 100644 Documentation/sphinx/alias.py

diff --git a/Documentation/arch/arc/index.rst b/Documentation/arch/arc/index.rst
index 7b098d4a5e3e..c2be040f04c3 100644
--- a/Documentation/arch/arc/index.rst
+++ b/Documentation/arch/arc/index.rst
@@ -15,3 +15,5 @@ ARC architecture
    =======
 
    * :ref:`genindex`
+
+.. alias:: arc/index
diff --git a/Documentation/arch/ia64/index.rst b/Documentation/arch/ia64/index.rst
index 761f2154dfa2..c4f973f17af2 100644
--- a/Documentation/arch/ia64/index.rst
+++ b/Documentation/arch/ia64/index.rst
@@ -17,3 +17,5 @@ IA-64 Architecture
    serial
 
    features
+
+.. alias:: ia64/index
diff --git a/Documentation/arch/index.rst b/Documentation/arch/index.rst
index 80ee31016584..11be66e23de4 100644
--- a/Documentation/arch/index.rst
+++ b/Documentation/arch/index.rst
@@ -26,3 +26,5 @@ implementation.
    sparc/index
    x86/index
    xtensa/index
+
+.. alias:: arch
diff --git a/Documentation/arch/m68k/index.rst b/Documentation/arch/m68k/index.rst
index 0f890dbb5fe2..9b5c34510fb7 100644
--- a/Documentation/arch/m68k/index.rst
+++ b/Documentation/arch/m68k/index.rst
@@ -18,3 +18,5 @@ m68k Architecture
    =======
 
    * :ref:`genindex`
+
+.. alias:: m68k/index
diff --git a/Documentation/arch/nios2/index.rst b/Documentation/arch/nios2/index.rst
index 4468fe1a1037..bfaf0e963db3 100644
--- a/Documentation/arch/nios2/index.rst
+++ b/Documentation/arch/nios2/index.rst
@@ -10,3 +10,5 @@ Nios II Specific Documentation
 
    nios2
    features
+
+.. alias:: nios2/index
diff --git a/Documentation/arch/openrisc/index.rst b/Documentation/arch/openrisc/index.rst
index 6879f998b87a..b59d97d6f8b7 100644
--- a/Documentation/arch/openrisc/index.rst
+++ b/Documentation/arch/openrisc/index.rst
@@ -18,3 +18,5 @@ OpenRISC Architecture
    =======
 
    * :ref:`genindex`
+
+.. alias:: openrisc/index
diff --git a/Documentation/arch/parisc/index.rst b/Documentation/arch/parisc/index.rst
index 240685751825..aaa708c7f98d 100644
--- a/Documentation/arch/parisc/index.rst
+++ b/Documentation/arch/parisc/index.rst
@@ -18,3 +18,5 @@ PA-RISC Architecture
    =======
 
    * :ref:`genindex`
+
+.. alias:: parisc/index
diff --git a/Documentation/arch/sh/index.rst b/Documentation/arch/sh/index.rst
index c64776738cf6..5a12d76abec4 100644
--- a/Documentation/arch/sh/index.rst
+++ b/Documentation/arch/sh/index.rst
@@ -54,3 +54,5 @@ Maple
 
 .. kernel-doc:: drivers/sh/maple/maple.c
    :export:
+
+.. alias:: sh/index
diff --git a/Documentation/arch/sparc/index.rst b/Documentation/arch/sparc/index.rst
index ae884224eec2..f2731a4925c3 100644
--- a/Documentation/arch/sparc/index.rst
+++ b/Documentation/arch/sparc/index.rst
@@ -11,3 +11,5 @@ Sparc Architecture
    oradax/oracle-dax
 
    features
+
+.. alias:: sparc/index
diff --git a/Documentation/arch/x86/index.rst b/Documentation/arch/x86/index.rst
index c73d133fd37c..2154bfe2b6ca 100644
--- a/Documentation/arch/x86/index.rst
+++ b/Documentation/arch/x86/index.rst
@@ -42,3 +42,5 @@ x86-specific Documentation
    features
    elf_auxvec
    xstate
+
+.. alias:: x86/index
diff --git a/Documentation/arch/x86/x86_64/index.rst b/Documentation/arch/x86/x86_64/index.rst
index a56070fc8e77..d4eb610b0080 100644
--- a/Documentation/arch/x86/x86_64/index.rst
+++ b/Documentation/arch/x86/x86_64/index.rst
@@ -15,3 +15,5 @@ x86_64 Support
    cpu-hotplug-spec
    machinecheck
    fsgs
+
+.. alias:: x86/x86_64/index
diff --git a/Documentation/arch/xtensa/index.rst b/Documentation/arch/xtensa/index.rst
index 69952446a9be..a794bddddad4 100644
--- a/Documentation/arch/xtensa/index.rst
+++ b/Documentation/arch/xtensa/index.rst
@@ -12,3 +12,5 @@ Xtensa Architecture
    mmu
 
    features
+
+.. alias:: xtensa/index
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 37314afd1ac8..068f85e5dd1f 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -16,6 +16,7 @@ import sys
 import os
 import sphinx
 import shutil
+from importlib.util import find_spec
 
 # helper
 # ------
@@ -57,6 +58,14 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
               'kernel_abi', 'kernel_feat']
 
+extensions += ['alias'] # uses rediraffe
+
+if find_spec('sphinxext.rediraffe'):
+    extensions += ['sphinxext.rediraffe']
+    rediraffe_redirects = { }
+else:
+    print("Skipping redirects because sphinxext.rediraffe is not installed")
+
 if major >= 3:
     if (major > 3) or (minor > 0 or patch >= 2):
         # Sphinx c function parser is more pedantic with regards to type
diff --git a/Documentation/sphinx/alias.py b/Documentation/sphinx/alias.py
new file mode 100644
index 000000000000..e00605d07dbd
--- /dev/null
+++ b/Documentation/sphinx/alias.py
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: GPL-2.0
+
+u"""
+    Directive `alias`
+    ~~~~~~~~~~~~~~~
+    Provides browser redirects for moved pages.
+
+    The directive declares previous path of a moved document as the argument.
+    Redirects are implemented with Sphinx extension rediraffe_redirects.
+
+    :copyright: Copyright 2023 Costa Shulyupin <[email protected]>
+    :license:   GPL Version 2, June 1991 see linux/COPYING for details.
+
+"""
+
+from docutils.parsers.rst import Directive
+import os
+
+
+class AliasDirective(Directive):
+    required_arguments = 1
+
+    def run(self):
+        env = self.state.document.settings.env
+        if 'rediraffe_redirects' not in env.config:
+            return []
+        env.config.rediraffe_redirects[self.arguments[0]] \
+            = os.path.relpath(self.state.document.current_source,
+                              env.srcdir)
+        return []
+
+
+def setup(app):
+    app.add_directive('alias', AliasDirective)
+    return { 'parallel_read_safe': False, 'parallel_write_safe': False }
diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 335b53df35e2..9ff99beb5ed3 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,3 +1,4 @@
 # jinja2>=3.1 is not compatible with Sphinx<4.0
 jinja2<3.1
 Sphinx==2.4.4
+rediraffe_redirects
-- 
2.40.0