admin/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2025-12-07 20:06:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: kernel_include.py: add support to generate a TOC table

Browse Source 
When generate-cross-refs is used, instead of just implementing
the default of generating a literal block, we can also
generate a ReST file as a TOC.

The advantage is that, by being a ReST file, missing references
will point to the place inside the header file that has the
broken link.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/c0d32cd1ef94017e05984b0a38bd2516f7db21e2.1755872208.git.mchehab+huawei@kernel.org
This commit is contained in:
Mauro Carvalho Chehab
2025-08-22 16:19:29 +02:00
committed by Jonathan Corbet
parent 9be2a5c3c8
commit e4d91787de
1 changed files with 22 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
Documentation/sphinx/kernel_include.py
View File

@@ -89,6 +89,7 @@ class KernelInclude(Include):
option_spec.update({
'generate-cross-refs': directives.flag,
'warn-broken': directives.flag,
'toc': directives.flag,
'exception-file': directives.unchanged,
})
@@ -111,7 +112,7 @@ class KernelInclude(Include):
except UnicodeError as error:
raise self.severe('Problem with directive:\n%s' % ErrorString(error))
def read_rawtext_with_xrefs(self, env, path):
def read_rawtext_with_xrefs(self, env, path, output_type):
parser = ParseDataStructs()
parser.parse_file(path)
@@ -126,7 +127,10 @@ class KernelInclude(Include):
if 'warn-broken' in self.options:
env._xref_files.add(path)
return parser.gen_output()
if output_type == "toc":
return parser.gen_toc()
return ".. parsed-literal::\n\n" + parser.gen_output()
def apply_range(self, rawtext):
# Get to-be-included content
@@ -243,39 +247,43 @@ class KernelInclude(Include):
e_handler = self.state.document.settings.input_encoding_error_handler
tab_width = self.options.get("tab-width",
self.state.document.settings.tab_width)
startline = self.options.get("start-line", None)
endline = self.options.get("end-line", None)
if "literal" in self.options:
ouptut_type = "literal"
output_type = "literal"
elif "code" in self.options:
ouptut_type = "code"
output_type = "code"
else:
ouptut_type = "normal"
output_type = "rst"
# Get optional arguments to related to cross-references generation
if 'generate-cross-refs' in self.options:
rawtext = self.read_rawtext_with_xrefs(env, path)
if "generate-cross-refs" in self.options:
if "toc" in self.options:
output_type = "toc"
rawtext = self.read_rawtext_with_xrefs(env, path, output_type)
# When :generate-cross-refs: is used, the input is always a C
# file, so it has to be handled as a parsed-literal
if output_type == "rst":
output_type = "literal"
title = os.path.basename(path)
if "code" not in self.options:
rawtext = ".. parsed-literal::\n\n" + rawtext
else:
rawtext = self.read_rawtext(path, encoding)
rawtext = self.apply_range(rawtext)
if ouptut_type == "literal":
if output_type == "literal":
return self.literal(path, tab_width, rawtext)
include_lines = statemachine.string2lines(rawtext, tab_width,
convert_whitespace=True)
if ouptut_type == "code":
if output_type == "code":
return self.code(path, include_lines)
self.state_machine.insert_input(include_lines, path)
return []
# ==============================================================================