tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
fork atom

docs: add tools/docs/gen-redirects.py

Add a new script and a new documentation 'make' target,
htmldocs-redirects.

This will generate HTML stub files in the HTML documentation output
directory that redirect the browser to the new path.

Suggested-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250905144608.577449-4-vegard.nossum@oracle.com>

authored by

Vegard Nossum and committed by
Jonathan Corbet f2c2f649 4b6fba46

+61 -2
+4
Documentation/Makefile
··· 108 108 @$(srctree)/scripts/sphinx-pre-install --version-check 109 109 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) 110 110 111 + htmldocs-redirects: $(srctree)/Documentation/.renames.txt 112 + @tools/docs/gen-redirects.py --output $(BUILDDIR) < $< 113 + 111 114 # If Rust support is available and .config exists, add rustdoc generated contents. 112 115 # If there are any, the errors from this make rustdoc will be displayed but 113 116 # won't stop the execution of htmldocs ··· 178 175 dochelp: 179 176 @echo ' Linux kernel internal documentation in different formats from ReST:' 180 177 @echo ' htmldocs - HTML' 178 + @echo ' htmldocs-redirects - generate HTML redirects for moved pages' 181 179 @echo ' texinfodocs - Texinfo' 182 180 @echo ' infodocs - Info' 183 181 @echo ' latexdocs - LaTeX'
+3 -2
Makefile
··· 1799 1799 1800 1800 # Documentation targets 1801 1801 # --------------------------------------------------------------------------- 1802 - DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \ 1803 - linkcheckdocs dochelp refcheckdocs texinfodocs infodocs 1802 + DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs htmldocs-redirects \ 1803 + epubdocs cleandocs linkcheckdocs dochelp refcheckdocs \ 1804 + texinfodocs infodocs 1804 1805 PHONY += $(DOC_TARGETS) 1805 1806 $(DOC_TARGETS): 1806 1807 $(Q)$(MAKE) $(build)=Documentation $@
+54
tools/docs/gen-redirects.py
··· 1 + #! /usr/bin/env python3 2 + # SPDX-License-Identifier: GPL-2.0 3 + # 4 + # Copyright © 2025, Oracle and/or its affiliates. 5 + # Author: Vegard Nossum <vegard.nossum@oracle.com> 6 + 7 + """Generate HTML redirects for renamed Documentation/**.rst files using 8 + the output of tools/docs/gen-renames.py. 9 + 10 + Example: 11 + 12 + tools/docs/gen-redirects.py --output Documentation/output/ < Documentation/.renames.txt 13 + """ 14 + 15 + import argparse 16 + import os 17 + import sys 18 + 19 + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) 20 + parser.add_argument('-o', '--output', help='output directory') 21 + 22 + args = parser.parse_args() 23 + 24 + for line in sys.stdin: 25 + line = line.rstrip('\n') 26 + 27 + old_name, new_name = line.split(' ', 2) 28 + 29 + old_html_path = os.path.join(args.output, old_name + '.html') 30 + new_html_path = os.path.join(args.output, new_name + '.html') 31 + 32 + if not os.path.exists(new_html_path): 33 + print(f"warning: target does not exist: {new_html_path} (redirect from {old_html_path})") 34 + continue 35 + 36 + old_html_dir = os.path.dirname(old_html_path) 37 + if not os.path.exists(old_html_dir): 38 + os.makedirs(old_html_dir) 39 + 40 + relpath = os.path.relpath(new_name, os.path.dirname(old_name)) + '.html' 41 + 42 + with open(old_html_path, 'w') as f: 43 + print(f"""\ 44 + <!DOCTYPE html> 45 + 46 + <html lang="en"> 47 + <head> 48 + <title>This page has moved</title> 49 + <meta http-equiv="refresh" content="0; url={relpath}"> 50 + </head> 51 + <body> 52 + <p>This page has moved to <a href="{relpath}">{new_name}</a>.</p> 53 + </body> 54 + </html>""", file=f)