Features/Documentation: Difference between revisions

From QEMU
No edit summary
Line 23: Line 23:
== Choices ==
== 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.
Based on experience from the Linux kernel, QEMU's docs pipeline is going to be based on Sphinx ([http://people.linaro.org/~peter.maydell/sphinx/memory.html sample developer doc], [http://people.redhat.com/pbonzini/qemu-test-doc/_build/html/ sample user doc].  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 ([http://docutils.sourceforge.net/ docutils]) parser for Docbook; Texinfo is able to convert .texi input files into Docbook.
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 ([http://docutils.sourceforge.net/ docutils]) parser for Docbook; Texinfo is able to convert .texi input files into Docbook.
Line 38: Line 38:
# Convert everything to Texinfo
# Convert everything to Texinfo
#:'''Advantages:''' qemu-doc.texi and command-line doc comments are already written in Texinfo, more traditional/"precise" markup
#:'''Advantages:''' qemu-doc.texi and command-line doc comments are already written in Texinfo, more traditional/"precise" markup
#:'''Disadvantages:''' Most different from basic ASCII text, not supported by kernel-doc
#:'''Disadvantages:''' Most different from basic ASCII text, markup not supported by kernel-doc, probably need some rST anyway for toctree directives and the like


For C doc comments, the three possible choices are:
For C doc comments, the three possible choices are:
Line 57: Line 57:


For now in no particular order:
For now in no particular order:
* Prepare five wiki pages to work collaboratively on the manuals' table of contents
* Prepare five wiki pages to work collaboratively on the manuals' table of contents, populate them with current qemu-doc.texi ToC and a list of docs/ files.
* Split qemu-doc.texi so that the bulk of its contents is included from small files in docs/
* Split qemu-doc.texi so that the bulk of its contents is included from small files in docs/
* Annotate developer documentation in {{src|path=docs/}} with the corresponding C source code, so as to prioritize where to add doc comments
* Annotate developer documentation in {{src|path=docs/}} with the corresponding C source code, so as to prioritize where to add doc comments

Revision as of 23:32, 7 November 2016

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 (sample developer doc, sample user doc. 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 should ultimately be:

  1. Convert everything to reStructuredText
    Advantages: Flexible enough, native format for Sphinx, Linux is using it
    Disadvantages: Less "obvious" than Markdown (though a basic conversion seems to be simple enough), looks somewhat weird when you use more advanced features
  2. Convert everything to Texinfo
    Advantages: qemu-doc.texi and command-line doc comments are already written in Texinfo, more traditional/"precise" markup
    Disadvantages: Most different from basic ASCII text, markup not supported by kernel-doc, probably need some rST anyway for toctree directives and the like

For C doc comments, the three possible choices are:

  1. Use reStructuredText markup
    Advantages: Flexible enough, native format for Sphinx, Linux is using it
    Disadvantages: Would not want to use rST for doc comments but not for the rest of docs/, or for command-line doc comments
  2. Extend kernel-doc to support Texinfo markup, and convert that to Docbook
    Advantages: qemu-doc.texi and command-line doc comments are already written in Texinfo
    Disadvantages: More work to do
  3. Use no markup, apart from annotating fields, functions etc. using sigils (e.g. kernel-doc's &struct Foo or GtkDoc's %Foo).
    Advantages: Simplest solution, can use any kernel-doc backend (DocBook and rST), doesn't conflict with chioce of format for docs/
    Disadvantages: none?

We should also choose whether to place comments close to the definition or the declaration of functions. Linux seems to place comments close to the definition—the disadvantage being that struct comments must obviously be placed in headers.

Things to do

For now in no particular order:

  • Prepare five wiki pages to work collaboratively on the manuals' table of contents, populate them with current qemu-doc.texi ToC and a list of docs/ files.
  • Split qemu-doc.texi so that the bulk of its contents is included from small files in docs/
  • Annotate developer documentation in docs/ with the corresponding C source code, so as to prioritize where to add doc comments