On 16:23 Tue 12 Dec , Peter Maydell wrote: > 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.mayd...@linaro.org>
Reviewed-by: Luc Michel <luc.mic...@amd.com> > --- > My motivation here is that we're about to add support for > extending the SRST directive to specify a label so we > can hyperlink to a documentation fragment; this gives us > somewhere we can document the syntax for that. > --- > MAINTAINERS | 1 + > docs/devel/docs.rst | 60 ++++++++++++++++++++++++++++++++++++++ > docs/devel/index-build.rst | 1 + > hmp-commands-info.hx | 10 +++---- > hmp-commands.hx | 10 +++---- > qemu-img-cmds.hx | 2 ++ > qemu-options.hx | 2 ++ > 7 files changed, 76 insertions(+), 10 deletions(-) > create mode 100644 docs/devel/docs.rst > > diff --git a/MAINTAINERS b/MAINTAINERS > index 695e0bd34fb..49b8ca9d1a8 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -4149,6 +4149,7 @@ F: docs/conf.py > F: docs/*/conf.py > F: docs/sphinx/ > F: docs/_templates/ > +F: docs/devel/docs.rst > > Miscellaneous > ------------- > diff --git a/docs/devel/docs.rst b/docs/devel/docs.rst > new file mode 100644 > index 00000000000..7da067905b8 > --- /dev/null > +++ b/docs/devel/docs.rst > @@ -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. > diff --git a/docs/devel/index-build.rst b/docs/devel/index-build.rst > index 57e8d39d985..90b406ca0ed 100644 > --- a/docs/devel/index-build.rst > +++ b/docs/devel/index-build.rst > @@ -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 > diff --git a/hmp-commands-info.hx b/hmp-commands-info.hx > index f5b37eb74ab..da120f82a32 100644 > --- a/hmp-commands-info.hx > +++ b/hmp-commands-info.hx > @@ -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 > diff --git a/hmp-commands.hx b/hmp-commands.hx > index 765349ed149..2db5701d49c 100644 > --- a/hmp-commands.hx > +++ b/hmp-commands.hx > @@ -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. > > > diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx > index 068692d13eb..c9dd70a8920 100644 > --- a/qemu-img-cmds.hx > +++ b/qemu-img-cmds.hx > @@ -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 > diff --git a/qemu-options.hx b/qemu-options.hx > index 42fd09e4de9..d3e31e65c25 100644 > --- a/qemu-options.hx > +++ b/qemu-options.hx > @@ -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. > -- > 2.34.1 > > --
