QEMU-Devel Archive on lore.kernel.org
 help / color / Atom feed
From: Miroslav Rezanina <mrezanin@redhat.com>
To: Peter Maydell <peter.maydell@linaro.org>
Cc: qemu-devel@nongnu.org, Michael Roth <mdroth@linux.vnet.ibm.com>
Subject: Re: [Qemu-devel] [PATCH v3] qemu-ga: Convert invocation documentation to rST
Date: Fri, 20 Sep 2019 10:57:56 +0200
Message-ID: <20190920085756.luzas76jivztgxzb@lws.brq.redhat.com> (raw)
In-Reply-To: <20190905131040.8350-1-peter.maydell@linaro.org>

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 <peter.maydell@linaro.org>
> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
> Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com>
> ---
> 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 <mdroth@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 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 <mdroth@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..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 <mdroth@linux.vnet.ibm.com>
> -@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


  parent reply index

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-05 13:10 Peter Maydell
2019-09-13 13:28 ` Peter Maydell
2019-09-13 22:12   ` Michael Roth
2019-09-20  8:57 ` Miroslav Rezanina [this message]
2019-09-20 10:52   ` Peter Maydell
2019-09-20 11:12     ` Miroslav Rezanina

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190920085756.luzas76jivztgxzb@lws.brq.redhat.com \
    --to=mrezanin@redhat.com \
    --cc=mdroth@linux.vnet.ibm.com \
    --cc=peter.maydell@linaro.org \
    --cc=qemu-devel@nongnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

QEMU-Devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/qemu-devel/0 qemu-devel/git/0.git
	git clone --mirror https://lore.kernel.org/qemu-devel/1 qemu-devel/git/1.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 qemu-devel qemu-devel/ https://lore.kernel.org/qemu-devel \
		qemu-devel@nongnu.org
	public-inbox-index qemu-devel

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.nongnu.qemu-devel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git