[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format questio
From: |
Peter Maydell |
Subject: |
Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question) |
Date: |
Mon, 7 Nov 2016 15:03:23 +0000 |
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
- [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Peter Maydell, 2016/11/05
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question),
Peter Maydell <=
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Paolo Bonzini, 2016/11/07
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Peter Maydell, 2016/11/07
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Paolo Bonzini, 2016/11/07
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Peter Maydell, 2016/11/07
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Paolo Bonzini, 2016/11/07
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Peter Maydell, 2016/11/07
Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Emilio G. Cota, 2016/11/08