[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v3] qemu-ga: Convert invocation documentation to
From: |
Miroslav Rezanina |
Subject: |
Re: [Qemu-devel] [PATCH v3] qemu-ga: Convert invocation documentation to rST |
Date: |
Fri, 20 Sep 2019 10:57:56 +0200 |
User-agent: |
NeoMutt/20180716 |
On Thu, Sep 05, 2019 at 02:10:40PM +0100, Peter Maydell wrote:
> 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>
> Reviewed-by: Michael Roth <address@hidden>
> Tested-by: Michael Roth <address@hidden>
> ---
> Now we're out of release we might as well get this in the tree.
> I saw a new manpage in texi going past the other day so perhaps
> if we have the framework for doing manpages in rst in-tree
> we can avoid adding too many more files we need to convert later.
>
> v2->v3:
> * no changes, just a rebase since this last went out in June
> v1->v2:
> * filter out built manpages when installing the HTML manual
> * default to /etc/qemu as the CONFDIR
> * rather than duplicating the whole sphinx command line in
> two macros, make the existing build-manual macro take an
> extra argument to specify html or manpage creation. This
> ensures we invoke the same way both times, which is important
> since sphinx might cache parts of the config in .doctrees
> * drop trailing '=' from 'key' column in table
> ---
> Makefile | 24 ++++---
> 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, 166 insertions(+), 161 deletions(-)
> create mode 100644 docs/interop/qemu-ga.rst
> delete mode 100644 qemu-ga.texi
>
> diff --git a/Makefile b/Makefile
> index ae17a830678..92acd6b4ee5 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -325,7 +325,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
> @@ -782,10 +782,11 @@ DESCS=
> endif
>
> # Note that we manually filter-out the non-Sphinx documentation which
> -# is currently built into the docs/interop directory in the build tree.
> +# is currently built into the docs/interop directory in the build tree,
> +# and also any sphinx-built manpages.
> define install-manual =
> for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR)
> "$(DESTDIR)$(qemu_docdir)/$$d"; done
> -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name
> 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_DATA)
> "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
> +for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name
> '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do
> $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
> endef
>
> # Note that we deliberately do not install the "devel" manual: it is
> @@ -817,7 +818,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"
> @@ -976,18 +977,22 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak
> sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html
> $(MANUAL_BUILDDIR)/interop/index.html $(MANUAL_BUILDDIR)/specs/index.html
>
> # Canned command to build a single manual
> -build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -W -n -b
> html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1
> $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
> +# Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')
> +build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build
> $(if $(V),,-q) -W -n -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)"
> -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1
> ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
> # 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
>
> $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)
> - $(call build-manual,devel)
> + $(call build-manual,devel,html)
>
> $(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
> - $(call build-manual,interop)
> + $(call build-manual,interop,html)
>
> $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
> - $(call build-manual,specs)
> + $(call build-manual,specs,html)
> +
> +$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)
> + $(call build-manual,interop,man)
>
> qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
> $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< >
> $@,"GEN","$@")
> @@ -1012,7 +1017,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
> @@ -1025,7 +1029,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-tech.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 ef6c01084b7..d7db933081b 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2032,7 +2032,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 e46b299b71f..b7edb0666b5 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', "/etc/qemu")
> +rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
> +
> # -- 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..1313a4ae1c9
> --- /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).
> +
> +Options
> +-------
> +
> +.. program:: qemu-ga
> +
> +.. option:: -m, --method=METHOD
> +
> + Transport method: one of ``unix-listen``, ``virtio-serial``, or
> + ``isa-serial`` (``virtio-serial`` is the default).
> +
> +.. option:: -p, --path=PATH
> +
> + Device/socket path (the default for virtio-serial is
> + ``/dev/virtio-ports/org.qemu.guest_agent.0``,
> + the default for isa-serial is ``/dev/ttyS0``)
> +
> +.. option:: -l, --logfile=PATH
> +
> + Set log file path (default is stderr).
> +
> +.. option:: -f, --pidfile=PATH
> +
> + Specify pid file (default is ``/var/run/qemu-ga.pid``).
> +
> +.. option:: -F, --fsfreeze-hook=PATH
> +
> + Enable fsfreeze hook. Accepts an optional argument that specifies
> + script to run on freeze/thaw. Script will be called with
> + 'freeze'/'thaw' arguments accordingly (default is
> + |CONFDIR|\ ``/fsfreeze-hook``). If using -F with an argument, do
> + not follow -F with a space (for example:
> + ``-F/var/run/fsfreezehook.sh``).
> +
> +.. option:: -t, --statedir=PATH
> +
> + Specify the directory to store state information (absolute paths only,
> + default is ``/var/run``).
> +
> +.. option:: -v, --verbose
> +
> + Log extra debugging information.
> +
> +.. option:: -V, --version
> +
> + Print version information and exit.
> +
> +.. option:: -d, --daemon
> +
> + Daemonize after startup (detach from terminal).
> +
> +.. option:: -b, --blacklist=LIST
> +
> + Comma-separated list of RPCs to disable (no spaces, ``?`` to list
> + available RPCs).
> +
> +.. option:: -D, --dump-conf
> +
> + Dump the configuration in a format compatible with ``qemu-ga.conf``
> + and exit.
> +
> +.. option:: -h, --help
> +
> + Display this help and exit.
> +
> +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
> +============= ===========
> +
> +See also
> +--------
> +
> +:manpage:`qemu(1)`
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 577d1e83764..fbdca1a992a 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -2525,11 +2525,6 @@ so should only be used with trusted guest OS.
>
> @c man end
>
> -@node QEMU Guest Agent
> -@chapter QEMU Guest Agent invocation
> -
> -@include qemu-ga.texi
> -
> @node QEMU User space emulator
> @chapter QEMU User space emulator
>
> diff --git a/qemu-ga.texi b/qemu-ga.texi
> deleted file mode 100644
> index f00ad830f28..00000000000
> --- a/qemu-ga.texi
> +++ /dev/null
> @@ -1,137 +0,0 @@
> -@example
> -@c man begin SYNOPSIS
> -@command{qemu-ga} [@var{OPTIONS}]
> -@c man end
> -@end example
> -
> -@c man begin 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:
> -
> -@itemize
> -@item
> -get information from the guest
> -@item
> -set the guest's system time
> -@item
> -read/write a file
> -@item
> -sync and freeze the filesystems
> -@item
> -suspend the guest
> -@item
> -reconfigure guest local processors
> -@item
> -set user's password
> -@item
> -...
> -@end itemize
> -
> -qemu-ga will read a system configuration file on startup (located at
> -@file{@value{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).
> -
> -@c man end
> -
> -@c man begin OPTIONS
> -@table @option
> -@item -m, --method=@var{method}
> - Transport method: one of @samp{unix-listen}, @samp{virtio-serial}, or
> - @samp{isa-serial} (@samp{virtio-serial} is the default).
> -
> -@item -p, --path=@var{path}
> - Device/socket path (the default for virtio-serial is
> - @samp{/dev/virtio-ports/org.qemu.guest_agent.0},
> - the default for isa-serial is @samp{/dev/ttyS0})
> -
> -@item -l, --logfile=@var{path}
> - Set log file path (default is stderr).
> -
> -@item -f, --pidfile=@var{path}
> - Specify pid file (default is @samp{/var/run/qemu-ga.pid}).
> -
> -@item -F, --fsfreeze-hook=@var{path}
> - Enable fsfreeze hook. Accepts an optional argument that specifies
> - script to run on freeze/thaw. Script will be called with
> - 'freeze'/'thaw' arguments accordingly (default is
> - @samp{@value{CONFDIR}/fsfreeze-hook}). If using -F with an argument, do
> - not follow -F with a space (for example:
> - @samp{-F/var/run/fsfreezehook.sh}).
> -
> -@item -t, --statedir=@var{path}
> - Specify the directory to store state information (absolute paths only,
> - default is @samp{/var/run}).
> -
> -@item -v, --verbose
> - Log extra debugging information.
> -
> -@item -V, --version
> - Print version information and exit.
> -
> -@item -d, --daemon
> - Daemonize after startup (detach from terminal).
> -
> -@item -b, --blacklist=@var{list}
> - Comma-separated list of RPCs to disable (no spaces, @samp{?} to list
> - available RPCs).
> -
> -@item -D, --dump-conf
> - Dump the configuration in a format compatible with @file{qemu-ga.conf}
> - and exit.
> -
> -@item -h, --help
> - Display this help and exit.
> -@end table
> -
> -@c man end
> -
> -@c man begin FILES
> -
> -The syntax of the @file{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.
> -
> -@example
> -# 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
> -@end example
> -
> -The list of keys follows the command line options:
> -@table @option
> -@item daemon= boolean
> -@item method= string
> -@item path= string
> -@item logfile= string
> -@item pidfile= string
> -@item fsfreeze-hook= string
> -@item statedir= string
> -@item verbose= boolean
> -@item blacklist= string list
> -@end table
> -
> -@c man end
> -
> -@ignore
> -
> -@setfilename qemu-ga
> -@settitle QEMU Guest Agent
> -
> -@c man begin AUTHOR
> -Michael Roth <address@hidden>
> -@c man end
> -
> -@c man begin SEEALSO
> -qemu(1)
> -@c man end
> -
> -@end ignore
> --
> 2.20.1
>
>
This patch is breaking build for me. It fails on:
perl -Ww -- /builddir/build/BUILD/qemu-4.1.0/scripts/texi2pod.pl -I docs -I
scripts -I docs/interop -DVERSION="4.1.50" -DCONFDIR="/etc/qemu-kvm"
scripts/texi2pod.pl docs/interop/qemu-ga.8.pod && pod2man --utf8 --section=8
--center=" " --release=" " docs/interop/qemu-ga.8.pod > docs/interop/qemu-ga.8
with:
No filename or title
Not sure why this is happening.
Miroslav Rezanina