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