Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Costa Shulyupin <costa.shul@redhat.com>
To:     Jonathan Corbet <corbet@lwn.net>,
        Mauro Carvalho Chehab <mchehab@kernel.org>,
        linux-doc@vger.kernel.org
Cc:     Costa Shulyupin <costa.shul@redhat.com>,
        linux-kernel@vger.kernel.org (open list)
Subject: [PATCH v2] docs: automatic redirects for moved pages
Date:   Mon,  1 May 2023 05:13:36 +0300
Message-Id: <20230501021338.182770-1-costa.shul@redhat.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

Problems:
- The documentation is not well-organized
- 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:
- To prevent the need for ongoing maintenance, extract renames
  from git log since specified age
- Input the renames into sphinx_reredirects module

Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>

---

Changes:
- added the extraction of renames from Git.

---
 Documentation/Makefile                |  8 +++++++-
 Documentation/conf.py                 | 17 ++++++++++++++++-
 Documentation/sphinx/requirements.txt |  1 +
 3 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 023fa658a0a8..fae385cf4d6d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -91,10 +91,16 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 		cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \
 	fi
 
-htmldocs:
+htmldocs: Documentation/redirects
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
 
+Documentation/redirects: $(srctree)/**/*.rst
+	git log --since="5 years ago" \
+		--name-status --find-renames=30 --diff-filter=R \
+		$(srctree)/Documentation/ \
+		| grep ^R | cut -f2,3 > $@
+
 texinfodocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 37314afd1ac8..16c5036992a0 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -16,6 +16,7 @@ import sys
 import os
 import sphinx
 import shutil
+import re
 
 # helper
 # ------
@@ -55,7 +56,21 @@ needs_sphinx = '1.7'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat',
+              'sphinx_reredirects',
+]
+
+redirects = dict()
+
+with open('redirects', 'r') as f:
+    for line in f:
+        p = r'Documentation/(.*)\.rst'
+        m = re.search(f'{p}\t{p}', line)
+        if not m or os.path.isfile(line.split()[0]):
+            continue
+        redirects[m.group(1) + '.html'] = os.path.relpath(m.group(2),
+            os.path.dirname(m.group(1))) + '.html'
+
 
 if major >= 3:
     if (major > 3) or (minor > 0 or patch >= 2):
diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 335b53df35e2..0b067e985edb 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
+sphinx_reredirects
-- 
2.40.0