docs/devel/docs: Document .hx file syntax

We don't currently document the syntax of .hx files anywhere
except in a few comments at the top of individual .hx files.
We don't even have somewhere in the developer docs where we
could do this.

Add a new files docs/devel/docs.rst which can be a place to
document how our docs build process works. For the moment,
put in only a brief introductory paragraph and the documentation
of the .hx files. We could later add to this file by for
example describing how the QAPI-schema-to-docs process works,
or anything else that developers might need to know about
how to add documentation.

Make the .hx files refer to this doc file, and clean
up their header comments to be more accurate for the
usage in each file and less cut-n-pasted.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Luc Michel <luc.michel@amd.com>
Reviewed-by: David Woodhouse <dwmw@amazon.co.uk>
Message-id: 20231212162313.1742462-1-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell 2023-12-12 16:23:13 +00:00
parent 977542ded7
commit d95f260aee
7 changed files with 76 additions and 10 deletions

View File

@ -4175,6 +4175,7 @@ F: docs/conf.py
F: docs/*/conf.py
F: docs/sphinx/
F: docs/_templates/
F: docs/devel/docs.rst
Miscellaneous
-------------

60
docs/devel/docs.rst Normal file
View File

@ -0,0 +1,60 @@
==================
QEMU Documentation
==================
QEMU's documentation is written in reStructuredText format and
built using the Sphinx documentation generator. We generate both
the HTML manual and the manpages from the some documentation sources.
hxtool and .hx files
--------------------
The documentation for QEMU command line options and Human Monitor Protocol
(HMP) commands is written in files with the ``.hx`` suffix. These
are processed in two ways:
* ``scripts/hxtool`` creates C header files from them, which are included
in QEMU to do things like handle the ``--help`` option output
* a Sphinx extension in ``docs/sphinx/hxtool.py`` generates rST output
to be included in the HTML or manpage documentation
The syntax of these ``.hx`` files is simple. It is broadly an
alternation of C code put into the C output and rST format text
put into the documention. A few special directives are recognised;
these are all-caps and must be at the beginning of the line.
``HXCOMM`` is the comment marker. The line, including any arbitrary
text after the marker, is discarded and appears neither in the C output
nor the documentation output.
``SRST`` starts a reStructuredText section. Following lines
are put into the documentation verbatim, and discarded from the C output.
``ERST`` ends the documentation section started with ``SRST``,
and switches back to a C code section.
``DEFHEADING()`` defines a heading that should appear in both the
``--help`` output and in the documentation. This directive should
be in the C code block. If there is a string inside the brackets,
this is the heading to use. If this string is empty, it produces
a blank line in the ``--help`` output and is ignored for the rST
output.
``ARCHHEADING()`` is a variant of ``DEFHEADING()`` which produces
the heading only if the specified guest architecture was compiled
into QEMU. This should be avoided in new documentation.
Within C code sections, you should check the comments at the top
of the file to see what the expected usage is, because this
varies between files. For instance in ``qemu-options.hx`` we use
the ``DEF()`` macro to define each option and specify its ``--help``
text, but in ``hmp-commands.hx`` the C code sections are elements
of an array of structs of type ``HMPCommand`` which define the
name, behaviour and help text for each monitor command.
In the file ``qemu-options.hx``, do not try to define a
reStructuredText label within a documentation section. This file
is included into two separate Sphinx documents, and some
versions of Sphinx will complain about the duplicate label
that results.

View File

@ -10,6 +10,7 @@ the basics if you are adding new files and targets to the build.
build-system
kconfig
docs
testing
acpi-bits
qtest

View File

@ -1,8 +1,8 @@
HXCOMM Use DEFHEADING() to define headings in both help text and rST.
HXCOMM Text between SRST and ERST is copied to the rST version and
HXCOMM discarded from C version.
HXCOMM DEF(command, args, callback, arg_string, help) is used to construct
HXCOMM monitor info commands
HXCOMM See docs/devel/docs.rst for the format of this file.
HXCOMM
HXCOMM This file defines the contents of an array of HMPCommand structs
HXCOMM which specify the name, behaviour and help text for HMP commands.
HXCOMM Text between SRST and ERST is rST format documentation.
HXCOMM HXCOMM can be used for comments, discarded from both rST and C.
HXCOMM
HXCOMM In this file, generally SRST fragments should have two extra

View File

@ -1,8 +1,8 @@
HXCOMM Use DEFHEADING() to define headings in both help text and rST.
HXCOMM Text between SRST and ERST is copied to the rST version and
HXCOMM discarded from C version.
HXCOMM DEF(command, args, callback, arg_string, help) is used to construct
HXCOMM monitor commands
HXCOMM See docs/devel/docs.rst for the format of this file.
HXCOMM
HXCOMM This file defines the contents of an array of HMPCommand structs
HXCOMM which specify the name, behaviour and help text for HMP commands.
HXCOMM Text between SRST and ERST is rST format documentation.
HXCOMM HXCOMM can be used for comments, discarded from both rST and C.

View File

@ -1,3 +1,5 @@
HXCOMM See docs/devel/docs.rst for the format of this file.
HXCOMM
HXCOMM Keep the list of subcommands sorted by name.
HXCOMM Use DEFHEADING() to define headings in both help text and rST
HXCOMM Text between SRST and ERST are copied to rST version and

View File

@ -1,3 +1,5 @@
HXCOMM See docs/devel/docs.rst for the format of this file.
HXCOMM
HXCOMM Use DEFHEADING() to define headings in both help text and rST.
HXCOMM Text between SRST and ERST is copied to the rST version and
HXCOMM discarded from C version.