Message ID | 20190905131040.8350-1-peter.maydell@linaro.org |
---|---|
State | New |
Headers | show |
Series | [v3] qemu-ga: Convert invocation documentation to rST | expand |
On Thu, 5 Sep 2019 at 14:10, Peter Maydell <peter.maydell@linaro.org> 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. I'm planning to put this into a target-arm pullreq since I'm doing one anyway. thanks -- PMM
Quoting Peter Maydell (2019-09-13 08:28:36) > On Thu, 5 Sep 2019 at 14:10, Peter Maydell <peter.maydell@linaro.org> 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. > > I'm planning to put this into a target-arm pullreq since > I'm doing one anyway. Ok, sounds good to me. > > thanks > -- PMM
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
On Fri, 20 Sep 2019 at 09:57, Miroslav Rezanina <mrezanin@redhat.com> wrote: > > 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 > 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. Yes, it's a bug in the handling of in-tree builds (out-of-tree builds work fine and we generally recommend those as better anyway). I have a patch on list which should fix the in-tree build case: https://patchew.org/QEMU/20190919155957.12618-1-peter.maydell@linaro.org/ thanks -- PMM
----- Original Message ----- > From: "Peter Maydell" <peter.maydell@linaro.org> > To: "Miroslav Rezanina" <mrezanin@redhat.com> > Cc: "QEMU Developers" <qemu-devel@nongnu.org>, "Michael Roth" <mdroth@linux.vnet.ibm.com> > Sent: Friday, September 20, 2019 12:52:49 PM > Subject: Re: [Qemu-devel] [PATCH v3] qemu-ga: Convert invocation documentation to rST > > On Fri, 20 Sep 2019 at 09:57, Miroslav Rezanina <mrezanin@redhat.com> wrote: > > > > 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 > > > > 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. > > Yes, it's a bug in the handling of in-tree builds (out-of-tree > builds work fine and we generally recommend those as better anyway). > I have a patch on list which should fix the in-tree build case: > > https://patchew.org/QEMU/20190919155957.12618-1-peter.maydell@linaro.org/ > Thanks for info, Mirek > thanks > -- PMM >
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