On 5 November 2016 at 18:42, Peter Maydell <peter.mayd...@linaro.org> 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 ".@fieldname" . "&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
