On Mon, 20 May 2019 at 19:41, Eduardo Habkost <ehabk...@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
