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 <peter.mayd...@linaro.org>
> ---
> 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 <mdr...@linux.vnet.ibm.com>
> 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 <mdr...@linux.vnet.ibm.com>'], 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!)
