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: kdoc: remove support for an external kernel-doc from sphinx

The ability to build the docs with an external kernel-doc program involves
some truly confusing logic and complicates the task of moving kernel-doc
out of scripts/. But this feature is not useful for normal documentation
builds, and the external kernel-doc can always be run by hand when it needs
debugging. So just remove that feature and make life easier.

There is still a bunch of logic to build a command line that we never use;
the idea is to be able to output it, but I'm not sure if that is worth
keeping.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <a97a8361546648906344457a7e92e4db533048a9.1768823489.git.mchehab+huawei@kernel.org>

Jonathan Corbet 24f984aa 6cc45ee5

+6 -47
+6 -47
Documentation/sphinx/kerneldoc.py
··· 190 190 191 191 return cmd 192 192 193 - def run_cmd(self, cmd): 194 - """ 195 - Execute an external kernel-doc command. 196 - """ 197 - 198 - env = self.state.document.settings.env 199 - node = nodes.section() 200 - 201 - p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) 202 - out, err = p.communicate() 203 - 204 - out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') 205 - 206 - if p.returncode != 0: 207 - sys.stderr.write(err) 208 - 209 - logger.warning("kernel-doc '%s' failed with return code %d" 210 - % (" ".join(cmd), p.returncode)) 211 - return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] 212 - elif env.config.kerneldoc_verbosity > 0: 213 - sys.stderr.write(err) 214 - 215 - filenames = self.parse_args["file_list"] 216 - for filename in filenames: 217 - self.parse_msg(filename, node, out, cmd) 218 - 219 - return node.children 220 - 221 - def parse_msg(self, filename, node, out, cmd): 193 + def parse_msg(self, filename, node, out): 222 194 """ 223 195 Handles a kernel-doc output for a given file 224 196 """ ··· 216 244 217 245 self.do_parse(result, node) 218 246 219 - def run_kdoc(self, cmd, kfiles): 247 + def run_kdoc(self, kfiles): 220 248 """ 221 249 Execute kernel-doc classes directly instead of running as a separate 222 250 command. ··· 230 258 filenames = self.parse_args["file_list"] 231 259 232 260 for filename, out in kfiles.msg(**self.msg_args, filenames=filenames): 233 - self.parse_msg(filename, node, out, cmd) 261 + self.parse_msg(filename, node, out) 234 262 235 263 return node.children 236 264 237 265 def run(self): 238 - global kfiles 239 - 240 266 cmd = self.handle_args() 241 267 if self.verbose >= 1: 242 268 logger.info(cmd_str(cmd)) 243 269 244 270 try: 245 - if kfiles: 246 - return self.run_kdoc(cmd, kfiles) 247 - else: 248 - return self.run_cmd(cmd) 249 - 271 + return self.run_kdoc(kfiles) 250 272 except Exception as e: # pylint: disable=W0703 251 273 logger.warning("kernel-doc '%s' processing failed with: %s" % 252 274 (cmd_str(cmd), pformat(e))) ··· 252 286 253 287 def setup_kfiles(app): 254 288 global kfiles 255 - 256 - kerneldoc_bin = app.env.config.kerneldoc_bin 257 - 258 - if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"): 259 - print("Using Python kernel-doc") 260 - out_style = RestFormat() 261 - kfiles = KernelFiles(out_style=out_style, logger=logger) 262 - else: 263 - print(f"Using {kerneldoc_bin}") 289 + out_style = RestFormat() 290 + kfiles = KernelFiles(out_style=out_style, logger=logger) 264 291 265 292 266 293 def setup(app):