Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation

[Peter Maydell <peter.maydell@linaro.org>]

On Mon, 20 May 2019 at 19:41, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> Please welcome GSoC student Gabriel Barreto.  Gabriel is going to
> work on QEMU API Documentation Generation[1].
>
> Gabriel's first task is to evaluate our options for extract doc
> comments from C source code and integrate them into Sphinx
> documentation.  I saw that Peter has experimented with kernel-doc
> in the past[2][3].  Has anybody evaluated other alternatives?
> (e.g. Hawkmoth[4])
>
> [1] https://wiki.qemu.org/Google_Summer_of_Code_2019#API_documentation_generation
> [2] https://www.mail-archive.com/qemu-devel@nongnu.org/msg411643.html
> [3] https://www.mail-archive.com/qemu-devel@nongnu.org/msg411841.html
> [4] https://readthedocs.org/projects/hawkmoth/

I think that kernel-doc is broadly where we'd decided we were
going with this. I have some in-progress patches that do
some integration of it: mostly just rebasing of the patches
in the git branch mentioned in your link [3] to be on top of
the sphinx support we now have in master. I'll just give
them a quick dusting off and push them out as an RFC, to
avoid duplication of work.

(The other interesting thing I'd wondered about with generation
of docs from code comments is whether we would get better
(ie more accurate, regularly updated) documentation of our
supported machine models if we generated those parts of the
docs from comments. But that's definitely much harder than just
getting API documentation, because it involves trying to
integrate them into a 'user documentation' manual which we
have not yet converted from texinfo.)

thanks
-- PMM