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. 33 34``ERST`` ends the documentation section started with ``SRST``, 35and switches back to a C code section. 36 37``DEFHEADING()`` defines a heading that should appear in both the 38``--help`` output and in the documentation. This directive should 39be in the C code block. If there is a string inside the brackets, 40this is the heading to use. If this string is empty, it produces 41a blank line in the ``--help`` output and is ignored for the rST 42output. 43 44``ARCHHEADING()`` is a variant of ``DEFHEADING()`` which produces 45the heading only if the specified guest architecture was compiled 46into QEMU. This should be avoided in new documentation. 47 48Within C code sections, you should check the comments at the top 49of the file to see what the expected usage is, because this 50varies between files. For instance in ``qemu-options.hx`` we use 51the ``DEF()`` macro to define each option and specify its ``--help`` 52text, but in ``hmp-commands.hx`` the C code sections are elements 53of an array of structs of type ``HMPCommand`` which define the 54name, behaviour and help text for each monitor command. 55 56In the file ``qemu-options.hx``, do not try to define a 57reStructuredText label within a documentation section. This file 58is included into two separate Sphinx documents, and some 59versions of Sphinx will complain about the duplicate label 60that results. 61