[PATCH v2] docs: automatic redirects for moved pages

[PATCH v2] docs: automatic redirects for moved pages

[Costa Shulyupin]

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

Re: [PATCH v2] docs: automatic redirects for moved pages

[Jonathan Corbet]

Costa Shulyupin <costa.shul@redhat.com> writes:

> 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(-)

So this adds another time-consuming process to the docs build,
generating over 2600 redirects, and breaking the build if it's not done
in a git tree.  All for a problem that still has not actually been
demonstrated to exist.

Costa, I appreciate that you are trying to help, but this is getting
worse, not better.  Please, let's wait until an actual problem arises,
then we can talk about the best way to address it.

Thanks,

jon