| 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. |