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. Thanks, jon
