On Mon, Nov 07, 2016 at 15:03:23 +0000, Peter Maydell wrote: > 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.
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 ".@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. FWIW I'd prefer to strictly adhere to kerneldoc as is. Converting the existing kerneldocs will require some supervision, anyway. E.
