On Fri, 18 Feb 2022, Matthew Wilcox <willy@xxxxxxxxxxxxx> wrote: > On Thu, Feb 17, 2022 at 10:04:23AM -0700, Jonathan Corbet wrote: >> *I* prefer Python, and the Sphinx side of things is necessarily in >> Python, so I'd be happy to see kernel-doc move over. That said, others >> certainly disagree. >> >> Markus's work was here: >> >> https://lore.kernel.org/lkml/1485287564-24205-1-git-send-email-markus.heiser@xxxxxxxxxxx/ >> >> At the time, we were just trying to get the RST transition done, and >> swapping out the kernel-doc script seemed like a major distraction that >> we didn't need, so this never got looked at as seriously as I would have >> liked. > > Personally, I'd like to see us switch over to > https://github.com/jnikula/hawkmoth > > but I don't have time to work on the rough edges. Basically Hawkmoth is my idea how C documentation comments should be incorporated to Sphinx *if* there is no legacy to care about. In that sense, I never wrote it with the kernel documentation in mind, on the contrary it's a hobby project where I can just not think about the kernel at all. ;) With that in mind, I'd really like to hear what the rough edges are that you see. Or are they kernel specific? Preferrably as issues on the project page if you don't mind. > I really hate the kernel-doc style; I think it makes us write very > stilted documentation, full of parameter descriptions like: > > function() - Do the thing to a page. > @page: The page. > > which really serves nobody. Being able to write: > > function() - Do the thing to @page > > is easier to both write and read. I tend to agree. Though Hawkmoth does not take a stand here, basically the assumption is that the documentation comments are pure rst. And that was one of the goals, no parsing of the comments beyond removing the C comment markers. It's up to the users or projects to dictate what the comments should look like. There's some plugin support for users to add their own filters, e.g. there could be kernel-doc format support via that. BR, Jani. -- Jani Nikula, Intel Open Source Graphics Center
