Messages in this thread | | | Subject | Re: [PATCH 1/2] Docs: An initial automarkup extension for sphinx | From | Markus Heiser <> | Date | Fri, 26 Apr 2019 13:31:15 +0200 |
| |
Am 26.04.19 um 11:06 schrieb Jani Nikula: > On Thu, 25 Apr 2019, Jonathan Corbet<corbet@lwn.net> wrote: >> Rather than fill our text files with :c:func:`function()` syntax, just do >> the markup via a hook into the sphinx build process. As is always the >> case, the real problem is detecting the situations where this markup should >> *not* be done. > This is basically a regex based pre-processing step in front of Sphinx, > but it's not independent as it embeds a limited understanding/parsing of > reStructuredText syntax. This is similar to what we do in kernel-doc the > Perl monster, except slightly different. > > I understand the motivation, and I sympathize with the idea of a quick > regex hack to silence the mob. But I fear this will lead to hard to > solve corner cases and the same style of "impedance mismatches" we had > with the kernel-doc/docproc/docbook Rube Goldberg machine of the past. > > 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. There were some > unresolved issues with e.g. replacing nodes that had syntax highlighting > (because I wanted to make the references work also within preformatted > blocks). > > 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.
FWIW mentioning: I fully agree with Jan.
-- Markus --
| |