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

[Emilio G. Cota]

On Mon, Nov 07, 2016 at 15:03:23 +0000, 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.

I moved qht's documentation to this to see how hard it was.
Was trivial to do! The result looks very nice. 

Patches here:
- Web:  https://github.com/cota/qemu/tree/sphinx-docs
- Git:  https://github.com/cota/qemu.git sphinx-docs

> 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).

Agreed.

> The branch above just puts the two example
> docs directly into the index.rst for demo purposes.
> 
> 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.
> 
> We could fix (2) by loosening the kernel-doc script's
> parsing if we were happy to carry around a forked version
> of it. Fixing (3) requires more serious surgery on kernel-doc
> I suspect.

FWIW I'd prefer to strictly adhere to kerneldoc as is. Converting
the existing kerneldocs will require some supervision, anyway.

                E.