Re: [PATCH for-9.0] docs/devel/docs: Document .hx file syntax

[Luc Michel <luc.michel@amd.com>]

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.maydell@linaro.org>

Reviewed-by: Luc Michel <luc.michel@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
> 
> 

--