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

[Peter Maydell]

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.

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.

I think this is probably sufficient for us to figure out
whether this is a path we want to proceed down, anyway.

thanks
-- PMM