[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Peter Maydell
Subject: Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation
Date: Tue, 21 May 2019 10:42:16 +0100

On Mon, 20 May 2019 at 19:41, Eduardo Habkost <address@hidden> 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/address@hidden/msg411643.html
> [3] https://www.mail-archive.com/address@hidden/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.)

-- PMM

reply via email to

[Prev in Thread] Current Thread [Next in Thread]