Features/Documentation
QEMU's documentation needs some reorganization.
Ultimately there should be five manuals:
- QEMU user mode emulation (docs/qemu-user)
- currently in qemu-doc.texi
- QEMU full-system emulation user's guide (docs/qemu-system)
- the largest part of qemu-doc.texi
- also covers qemu-img, qemu-io
- parts of docs/
- QEMU full-system emulation management guide (docs/qemu-system-mgmt)
- qmp-commands.txt
- docs/specs/vhost-user.txt
- probably should include file format specs in docs/specs/
- QEMU full-system emulation guest hardware specifications (docs/qemu-system-hw)
- currently in docs/specs/
- QEMU developer's guide (docs/qemu-devel)
- the rest of docs/
- the implementation notes in qemu-doc.texi
- tcg/README
- doc comments in the source code
- automatically generated docs for Python classes in qemu-iotests and scripts/qmp
Choices
Based on experience from the Linux kernel, QEMU's docs pipeline is going to be based on Sphinx. Sphinx is extensible and it is easy to add new input formats and input directives.
Currently, QEMU documentation is written in a mix of Texinfo and text files roughly based on Markdown. Sphinx's native format is reStructuredText (rST). Texinfo input is not supported by Sphinx, but Paolo has a Sphinx (docutils) parser for Docbook; Texinfo is able to convert .texi input files into Docbook.
Currently, QEMU doc comments have never been actually used together with a actual documentation generator in mind, but are roughly based on gtk-doc syntax. We will probably end up keeping a copy of the Linux kernel's kernel-doc script. kernel-doc currently supports rST and Docbook output.
As a first step, we should decide how to evolve this into something more structured.
For text, the two possible choices are:
- Convert everything to reStructuredText
- Convert everything to Texinfo
For comments, the three possible choices are:
- Use reStructuredText markup
- Extend kernel-doc to support Texinfo markup, and convert that to Docbook
- Use no markup, apart from annotating fields, functions etc. using sigils (e.g. kernel-doc's &struct Foo or GtkDoc's %Foo).
Things to do
For now in no particular order:
- Reorganize the docs/ directory to reflect which files will end up in which manual
- Split qemu-doc.texi so that the bulk of its contents comes from docs/