docs/devel/docs.rst

   1
   2 ==================
   3 QEMU Documentation
   4 ==================
   5
   6 QEMU's documentation is written in reStructuredText format and
   7 built using the Sphinx documentation generator. We generate both
   8 the HTML manual and the manpages from the some documentation sources.
   9
  10 hxtool and .hx files
  11 --------------------
  12
  13 The documentation for QEMU command line options and Human Monitor Protocol
  14 (HMP) commands is written in files with the ``.hx`` suffix. These
  15 are processed in two ways:
  16
  17  * ``scripts/hxtool`` creates C header files from them, which are included
  18    in QEMU to do things like handle the ``--help`` option output
  19  * a Sphinx extension in ``docs/sphinx/hxtool.py`` generates rST output
  20    to be included in the HTML or manpage documentation
  21
  22 The syntax of these ``.hx`` files is simple. It is broadly an
  23 alternation of C code put into the C output and rST format text
  24 put into the documentation. A few special directives are recognised;
  25 these are all-caps and must be at the beginning of the line.
  26
  27 ``HXCOMM`` is the comment marker. The line, including any arbitrary
  28 text after the marker, is discarded and appears neither in the C output
  29 nor the documentation output.
  30
  31 ``SRST`` starts a reStructuredText section. Following lines
  32 are put into the documentation verbatim, and discarded from the C output.
  33 The alternative form ``SRST()`` is used to define a label which can be
  34 referenced from elsewhere in the rST documentation. The label will take
  35 the form ``<DOCNAME-HXFILE-LABEL>``, where ``DOCNAME`` is the name of the
  36 top level rST file, ``HXFILE`` is the filename of the .hx file without
  37 the ``.hx`` extension, and ``LABEL`` is the text provided within the
  38 ``SRST()`` directive. For example,
  39 ``<system/invocation-qemu-options-initrd>``.
  40
  41 ``ERST`` ends the documentation section started with ``SRST``,
  42 and switches back to a C code section.
  43
  44 ``DEFHEADING()`` defines a heading that should appear in both the
  45 ``--help`` output and in the documentation. This directive should
  46 be in the C code block. If there is a string inside the brackets,
  47 this is the heading to use. If this string is empty, it produces
  48 a blank line in the ``--help`` output and is ignored for the rST
  49 output.
  50
  51 ``ARCHHEADING()`` is a variant of ``DEFHEADING()`` which produces
  52 the heading only if the specified guest architecture was compiled
  53 into QEMU. This should be avoided in new documentation.
  54
  55 Within C code sections, you should check the comments at the top
  56 of the file to see what the expected usage is, because this
  57 varies between files. For instance in ``qemu-options.hx`` we use
  58 the ``DEF()`` macro to define each option and specify its ``--help``
  59 text, but in ``hmp-commands.hx`` the C code sections are elements
  60 of an array of structs of type ``HMPCommand`` which define the
  61 name, behaviour and help text for each monitor command.
  62
  63 In the file ``qemu-options.hx``, do not try to explicitly define a
  64 reStructuredText label within a documentation section. This file
  65 is included into two separate Sphinx documents, and some
  66 versions of Sphinx will complain about the duplicate label
  67 that results. Use the ``SRST()`` directive documented above, to
  68 emit an unambiguous label.