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@xxxxxxxxxx>
---
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
