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 <[email protected]>
---
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
Costa Shulyupin <[email protected]> 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 <[email protected]>
>
> ---
>
> 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