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

Configure Feed

Select the types of activity you want to include in your feed.

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

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

authored by

Mauro Carvalho Chehab and committed by
Jonathan Corbet e4d91787 9be2a5c3

+22 -14
+22 -14
Documentation/sphinx/kernel_include.py
··· 89 89 option_spec.update({ 90 90 'generate-cross-refs': directives.flag, 91 91 'warn-broken': directives.flag, 92 + 'toc': directives.flag, 92 93 'exception-file': directives.unchanged, 93 94 }) 94 95 ··· 112 111 except UnicodeError as error: 113 112 raise self.severe('Problem with directive:\n%s' % ErrorString(error)) 114 113 115 - def read_rawtext_with_xrefs(self, env, path): 114 + def read_rawtext_with_xrefs(self, env, path, output_type): 116 115 parser = ParseDataStructs() 117 116 parser.parse_file(path) 118 117 ··· 127 126 if 'warn-broken' in self.options: 128 127 env._xref_files.add(path) 129 128 130 - return parser.gen_output() 129 + if output_type == "toc": 130 + return parser.gen_toc() 131 + 132 + return ".. parsed-literal::\n\n" + parser.gen_output() 131 133 132 134 def apply_range(self, rawtext): 133 135 # Get to-be-included content ··· 247 243 e_handler = self.state.document.settings.input_encoding_error_handler 248 244 tab_width = self.options.get("tab-width", 249 245 self.state.document.settings.tab_width) 250 - startline = self.options.get("start-line", None) 251 - endline = self.options.get("end-line", None) 252 246 253 247 if "literal" in self.options: 254 - ouptut_type = "literal" 248 + output_type = "literal" 255 249 elif "code" in self.options: 256 - ouptut_type = "code" 250 + output_type = "code" 257 251 else: 258 - ouptut_type = "normal" 252 + output_type = "rst" 259 253 260 254 # Get optional arguments to related to cross-references generation 261 - if 'generate-cross-refs' in self.options: 262 - rawtext = self.read_rawtext_with_xrefs(env, path) 255 + if "generate-cross-refs" in self.options: 256 + if "toc" in self.options: 257 + output_type = "toc" 258 + 259 + rawtext = self.read_rawtext_with_xrefs(env, path, output_type) 260 + 261 + # When :generate-cross-refs: is used, the input is always a C 262 + # file, so it has to be handled as a parsed-literal 263 + if output_type == "rst": 264 + output_type = "literal" 263 265 264 266 title = os.path.basename(path) 265 - 266 - if "code" not in self.options: 267 - rawtext = ".. parsed-literal::\n\n" + rawtext 268 267 else: 269 268 rawtext = self.read_rawtext(path, encoding) 270 269 271 270 rawtext = self.apply_range(rawtext) 272 271 273 - if ouptut_type == "literal": 272 + if output_type == "literal": 274 273 return self.literal(path, tab_width, rawtext) 275 274 276 275 include_lines = statemachine.string2lines(rawtext, tab_width, 277 276 convert_whitespace=True) 278 277 279 - if ouptut_type == "code": 278 + if output_type == "code": 280 279 return self.code(path, include_lines) 281 280 282 281 self.state_machine.insert_input(include_lines, path) 282 + 283 283 return [] 284 284 285 285 # ==============================================================================