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