Hi; I had a play on Friday afternoon with Sphinx, which is the restructured-text documentation processor that the Linux kernel is just switching to for their documentation. My first impression is that it would probably be useful for us too (and if the kernel is using it this also suggests that it's a fairly reasonable tool to rely on that isn't going to stagnate or vanish on us).
In particular I think we could: * set up a framework for our in-tree docs/ which gives us a place to put new docs (both for-users and for-developers) -- I think having someplace to put things will reduce the barrier to people writing useful new docs * gradually convert the existing docs to rst * use the sphinx extension features to pull in the doc-comments we have been fairly consistently writing over the last few years (for instance a converted version of docs/memory.txt could pull in doc comments from memory.h; or we can just write simple wrapper files like a "Bitmap operations" document that displays the doc comments from bitops.h) * eventually replace our current use of texinfo, since Sphinx can output PDF and manpages as well as HTML Because Sphinx only parses doc-comments in files when a .rst document in the tree specifically asks for them, this means we can do a gradual transition. (Tools like gtkdoc want to parse every file in the tree at once which gives a nasty big-bang requirement to fix a lot of doc comment syntax errors all at once.) This does raise the question though of what format our doc comments actually are. Because we haven't been running any kind of document tool on the code there's been no syntax checking, so I suspect what we have in practice is a bit of a mishmash. The original intent I think was that they were gtkdoc format, but we also have some kernel-doc format comments (where we've borrowed headers from the kernel, and then subsequently copied that style in other doc comments), and probably some which aren't any formal syntax at all. We have as for as I can see just 3 gtkdoc "SECTION:" markers for doc-comments which aren't just documenting a particular function, type or structure. Since the doc-comment parsing is handled by a Sphinx extension (which is in Python), we could in theory pick any syntax we liked. However if we said "use kernel-doc" we would be able to just borrow the kernel's kernel-doc extension without having to do a load of hacking on it (instead we'd need to fix up doc comments when we added documentation files that read in those source files, but we will need to do some of that anyway to fix accidental syntax errors). Does anybody have strong opinions on doc-comment formats? Anybody with experience with the kernel-doc format and views on any shortcomings? Sphinx is packaged in Debian stable so hopefully for most developers it would not be "bleeding edge have to have a custom install of this" tooling. For an idea of how the docs tend to come out, see https://readthedocs.org/ which collects formatted docs for a large number of Sphinx-using projects. There are a couple of LWN articles about Sphinx for the kernel if you want more detail: https://lwn.net/Articles/692704/ With a little luck I may be able to put something up on Monday as a sort of minimal-demonstration of how this would look in QEMU. thanks -- PMM