Re: [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST

[Michael Roth]

Quoting Peter Maydell (2019-06-10 08:45:45)
> The qemu-ga documentation is currently in qemu-ga.texi in
> Texinfo format, which we present to the user as:
>  * a qemu-ga manpage
>  * a section of the main qemu-doc HTML documentation
> 
> Convert the documentation to rST format, and present it to
> the user as:
>  * a qemu-ga manpage
>  * part of the interop/ Sphinx manual
> 
> Signed-off-by: Peter Maydell <address@hidden>
> ---
> This is part of my general proposals about how we should
> transition away from texinfo to sphinx (written up at
> https://wiki.qemu.org/Features/Documentation). It's the
> first part of step 3 (convert standalone manpages), so it's
> interesting as a demonstration of Sphinx generating manpages
> as well as HTML. The format of the output manpage is broadly
> the same, though there are a few minor differences because
> rST doesn't support quite the same kinds of output. (It also
> fixes a bug where the current manpage renders some text intended
> to be in bold as literally "B<unix-listen>".)
> 
> Having the infrastructure for creating a simple manpage via
> Sphinx should be a useful assist for the work in step 1 of the
> transition plan that involves conversion of the auto-generated
> qemu-ga-ref and qemu-qmp-ref (which need to produce manpages).
> 
> The non-manpage HTML version of the doc moves from qemu-doc.html
> into docs/interop/ (its final location in the new 5-manual setup).
> 
>  Makefile                 |  13 ++--
>  MAINTAINERS              |   2 +-
>  docs/conf.py             |  18 ++---
>  docs/interop/conf.py     |   7 ++
>  docs/interop/index.rst   |   1 +
>  docs/interop/qemu-ga.rst | 133 +++++++++++++++++++++++++++++++++++++
>  qemu-doc.texi            |   5 --
>  qemu-ga.texi             | 137 ---------------------------------------
>  8 files changed, 161 insertions(+), 155 deletions(-)
>  create mode 100644 docs/interop/qemu-ga.rst
>  delete mode 100644 qemu-ga.texi
> 
> diff --git a/Makefile b/Makefile
> index 8e2fc6624c3..cdada210746 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -329,7 +329,7 @@ endif
>  endif
> 
>  ifdef BUILD_DOCS
> -DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8
> +DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 
> docs/interop/qemu-ga.8
>  DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt 
> docs/interop/qemu-qmp-ref.7
>  DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt 
> docs/interop/qemu-ga-ref.7
>  DOCS+=docs/qemu-block-drivers.7
> @@ -804,7 +804,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP
>         $(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
>  endif
>  ifneq (,$(findstring qemu-ga,$(TOOLS)))
> -       $(INSTALL_DATA) qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
> +       $(INSTALL_DATA) docs/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
>         $(INSTALL_DATA) docs/interop/qemu-ga-ref.html 
> "$(DESTDIR)$(qemu_docdir)"
>         $(INSTALL_DATA) docs/interop/qemu-ga-ref.txt 
> "$(DESTDIR)$(qemu_docdir)"
>         $(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7"
> @@ -969,12 +969,18 @@ build-manual = $(call quiet-command,sphinx-build $(if 
> $(V),,-q) -W -n -b html -D
>  # We assume all RST files in the manual's directory are used in it
>  manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) 
> $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
> 
> +# Canned command to build manpages from a single manual
> +build-manpages = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build 
> $(if $(V),,-q) -W -n -b man -D version=$(VERSION) -D 
> release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 
> $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
> +
>  $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)
>         $(call build-manual,devel)
> 
>  $(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
>         $(call build-manual,interop)
> 
> +$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)
> +       $(call build-manpages,interop)
> +
>  qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
>         $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > 
> $@,"GEN","$@")
> 
> @@ -998,7 +1004,6 @@ qemu.1: qemu-option-trace.texi
>  qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi
>  fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
>  qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi
> -qemu-ga.8: qemu-ga.texi
>  docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
>  docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
>  scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
> @@ -1010,7 +1015,7 @@ txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt 
> docs/interop/qemu-ga-ref.txt
> 
>  qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
>         qemu-img.texi qemu-nbd.texi qemu-options.texi qemu-option-trace.texi \
> -       qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi 
> qemu-ga.texi \
> +       qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \
>         qemu-monitor-info.texi docs/qemu-block-drivers.texi \
>         docs/qemu-cpu-models.texi docs/security.texi
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index a96829ea83a..27a6ffa7431 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2024,7 +2024,7 @@ QEMU Guest Agent
>  M: Michael Roth <address@hidden>
>  S: Maintained
>  F: qga/
> -F: qemu-ga.texi
> +F: docs/interop/qemu-ga.rst
>  F: scripts/qemu-guest-agent/
>  F: tests/test-qga.c
>  F: docs/interop/qemu-ga-ref.texi
> diff --git a/docs/conf.py b/docs/conf.py
> index befbcc6c3e1..d34a94838ca 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -115,6 +115,14 @@ todo_include_todos = False
>  # with "option::" in the document being processed. Turn that off.
>  suppress_warnings = ["ref.option"]
> 
> +# The rst_epilog fragment is effectively included in every rST file.
> +# We use it to define substitutions based on build config that
> +# can then be used in the documentation. The fallback if the
> +# environment variable is not set is for the benefit of readthedocs
> +# style document building; our Makefile always sets the variable.
> +confdir = os.getenv('CONFDIR', "/usr/local/etc")
> +rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
> +

When testing this I have the following in my qemu build directory (via
./configure --prefix=/home/mdroth/w/qemu-install2):

  $ grep -r CONFDIR
  config-host.h-timestamp:#define CONFIG_QEMU_CONFDIR 
"/home/mdroth/w/qemu-install2/etc/qemu"
  qemu-doc.txt:     user-provided config files on SYSCONFDIR.
  config-host.h:#define CONFIG_QEMU_CONFDIR 
"/home/mdroth/w/qemu-install2/etc/qemu"
  docs/version.texi:@set CONFDIR /home/mdroth/w/qemu-install2/etc/qemu

but the following input for the qemu-ga man page:

  qemu-ga will read a system configuration file on startup (located at
  |CONFDIR|\ ``/qemu-ga.conf`` by default),

ends up as this in the generated man page:

  qemu-ga will read a system configuration file on startup (located at 
/usr/local/etc/qemu-ga.conf
  by  default),

is this expected, or are we unexpectedly falling back to the default
value here?


>  # -- Options for HTML output ----------------------------------------------
> 
>  # The theme to use for HTML and HTML Help pages.  See the documentation for
> @@ -192,14 +200,8 @@ latex_documents = [
> 
> 
>  # -- Options for manual page output ---------------------------------------
> -
> -# One entry per manual page. List of tuples
> -# (source start file, name, description, authors, manual section).
> -man_pages = [
> -    (master_doc, 'qemu', u'QEMU Documentation',
> -     [author], 1)
> -]
> -
> +# Individual manual/conf.py can override this to create man pages
> +man_pages = []
> 
>  # -- Options for Texinfo output -------------------------------------------
> 
> diff --git a/docs/interop/conf.py b/docs/interop/conf.py
> index cf3c69d4a7e..e87b8c22bec 100644
> --- a/docs/interop/conf.py
> +++ b/docs/interop/conf.py
> @@ -13,3 +13,10 @@ exec(compile(open(parent_config, "rb").read(), 
> parent_config, 'exec'))
>  # This slightly misuses the 'description', but is the best way to get
>  # the manual title to appear in the sidebar.
>  html_theme_options['description'] = u'System Emulation Management and 
> Interoperability Guide'
> +
> +# One entry per manual page. List of tuples
> +# (source start file, name, description, authors, manual section).
> +man_pages = [
> +    ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
> +     ['Michael Roth <address@hidden>'], 8)
> +]
> diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> index b4bfcab4171..3e33fb59332 100644
> --- a/docs/interop/index.rst
> +++ b/docs/interop/index.rst
> @@ -15,5 +15,6 @@ Contents:
>     bitmaps
>     live-block-operations
>     pr-helper
> +   qemu-ga
>     vhost-user
>     vhost-user-gpu
> diff --git a/docs/interop/qemu-ga.rst b/docs/interop/qemu-ga.rst
> new file mode 100644
> index 00000000000..56e17f27fca
> --- /dev/null
> +++ b/docs/interop/qemu-ga.rst
> @@ -0,0 +1,133 @@
> +QEMU Guest Agent
> +================
> +
> +Synopsis
> +--------
> +
> +**qemu-ga** [*OPTIONS*]
> +
> +Description
> +-----------
> +
> +The QEMU Guest Agent is a daemon intended to be run within virtual
> +machines. It allows the hypervisor host to perform various operations
> +in the guest, such as:
> +
> +- get information from the guest
> +- set the guest's system time
> +- read/write a file
> +- sync and freeze the filesystems
> +- suspend the guest
> +- reconfigure guest local processors
> +- set user's password
> +- ...
> +
> +qemu-ga will read a system configuration file on startup (located at
> +|CONFDIR|\ ``/qemu-ga.conf`` by default), then parse remaining
> +configuration options on the command line. For the same key, the last
> +option wins, but the lists accumulate (see below for configuration
> +file format).
> +

<snip>

> +Files
> +-----
> +
> +
> +The syntax of the ``qemu-ga.conf`` configuration file follows the
> +Desktop Entry Specification, here is a quick summary: it consists of
> +groups of key-value pairs, interspersed with comments.
> +
> +::
> +
> +    # qemu-ga configuration sample
> +    [general]
> +    daemonize = 0
> +    pidfile = /var/run/qemu-ga.pid
> +    verbose = 0
> +    method = virtio-serial
> +    path = /dev/virtio-ports/org.qemu.guest_agent.0
> +    statedir = /var/run
> +
> +The list of keys follows the command line options:
> +
> +==============  ===========
> +Key             Key type
> +==============  ===========
> +daemon=         boolean
> +method=         string
> +path=           string
> +logfile=        string
> +pidfile=        string
> +fsfreeze-hook=  string
> +statedir=       string
> +verbose=        boolean
> +blacklist=      string list
> +==============  ===========

Sphinx seems to do a better job of formatting "Key" and "Key type" into
actual table columns in the generated man/html pages (rather than just
separating them with whitespace), so I think we can drop the trailing '='s

Looks good otherwise (and much nicer!)