Em Fri, 26 Apr 2019 10:52:09 -0600 Jonathan Corbet <corbet@xxxxxxx> escreveu: > On Fri, 26 Apr 2019 12:06:42 +0300 > Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> wrote: > > > It's more involved, but I think the better place to do this (as well as > > the kernel-doc transformations) would be in the doctree-read event, > > after the rst parsing is done. You can traverse the doctree and find the > > places which weren't special for Sphinx, and replace the plain text > > nodes in-place. I've toyed with this in the past, but alas I didn't have > > (and still don't) have the time to finish the job. > > I had thought about this; indeed, there's a comment in the posted patch to > that effect. The tradeoff comes down to this, I think: > > - The fragility and inelegance of embedding a bit of redundant RST > parsing into this extension v. that of adding a late parsing stage as a > transform, trying to enumerate every node type that you might want to > change, and digging into the C domain code to emulate its reference > generation. > > - The time required to implement a solution; I'm having a bit of a hard > time keeping up with docs at the moment as it is. > > - Regexes. This solution has more of them, but we're not going to get > away from them regardless. > > I am not at all opposed to a more proper solution that might, in the > long term, produce more deterministic results. I can even try to work in > that direction. But this is something that can be done now that, IMO, > doesn't in any way close off a better implementation in the future. If we > agree that we should automatically generate references for occurrences of > "function()", we can change how that is actually done later. > > I'll look into this further, but my inclination is to go forward with what > I have now. It's simple and easy to understand, and doesn't seem to screw > up anywhere in the current body of kernel docs as far as I can tell. > > > If you decide to go with regex anyway, I'd at least consider pulling the > > transformations/highlights from kernel-doc the script to the Sphinx > > extension, and use the exact same transformations for stuff in source > > code comments and rst files. > > Pulling all RST manipulation out of kerneldoc has a great deal of appeal; > assuming this goes forward that should indeed be high on the todo list. While I didn't review the python code yet, and while I agree with Jani and Markus that it would be better only parse functions on texts after the Sphinx parser, I agree with Jon on that: if the current code works well enough with the current documentation, I would proceed and apply it. Later, the script can be improved. Thanks, Mauro
