Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question)

[Paolo Bonzini]

On 07/11/2016 16:03, Peter Maydell wrote:
> On 5 November 2016 at 18:42, Peter Maydell <address@hidden> wrote:
>> 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.
> 
> Generated documentation:
>   http://people.linaro.org/~peter.maydell/sphinx/index.html
> Git branch with the patches needed to produce that:
>   https://git.linaro.org/people/peter.maydell/qemu-arm.git sphinx-docs
> Pointy-clicky interface to git branch:
>   https://git.linaro.org/people/peter.maydell/qemu-arm.git/log/?h=sphinx-docs
> 
> I didn't bother to write the makefile changes to tie it into
> the main build process, so to regenerate the docs locally you'll
> need to run
>  sphinx-build -b html docs my-build-dir/docs
> from the QEMU source tree root, which will put the output into
> my-build-dir/docs, which you can then point your web browser at.
> 
> The overall organisation structure needs some thought --
> I think we should at least separate into user/ for user
> docs and dev/ for internals docs (and only install the
> user/ docs). The branch above just puts the two example
> docs directly into the index.rst for demo purposes.

Yes, the complicated part is establishing a structure for the
documentation (this should be done collaboratively on the wiki, I think).

Ultimately we should have three manuals: user, developer and hardware
specifications, but docs/ is currently a hodge-podge of the first two.
Once we have that, it is possible to add bits from docs/ into
Sphinx-built manuals, and/or disintegrate qemu-doc into docs/ files.

For what it's worth, I played with building QEMU's texinfo documentation
with Sphinx.  The result is at
http://people.redhat.com/pbonzini/qemu-test-doc/ and it works by
converting Texinfo->docbook (XML) with makeinfo, and then using a custom
parser (a Sphinx extension) to process the output.  It should be easy to
modify it so that Python spawns makeinfo and then pipes the output back
into the parser.

Personally, I prefer Texinfo (aka "LaTeX with @ instead of \" :)) to
either restructuredText and Markdown, but I understand that the more
nonstandard pieces you add to the toolchain has disadvantages, the more
it becomes a maintenance hassle.  However, I'll note that Marc-André's
work on automatically-generated QAPI documentation also used Texinfo.

I guess it also depends on whether we want to fork kerneldoc or not,
and/or whether the kernel guys are okay with adding another backend to
kerneldoc.

> Conclusions from this exercise:
> 1) conversion isn't all that difficult, and the results
>    look pretty nice
> 2) some of the doc-comment format differences are irritating:
>    . "function - short description" not "function: short description"
>    . "&struct.fieldname" not "address@hidden"
>    . "&typename" not "#typename"
> 3) the most awkward part of kernel-doc syntax is that it bakes
>    in the kernel's style choice of always using "struct foo"
>    for types -- I don't think there's any way to document
>    'MemoryRegion' and 'AddressSpace' without the 'struct'
>    coming out in the documentation output.

I actually like having struct in the name, even if the code then doesn't
use it.

Paolo