* [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST
@ 2019-06-10 13:45 Peter Maydell
2019-06-10 13:56 ` Paolo Bonzini
` (2 more replies)
0 siblings, 3 replies; 7+ messages in thread
From: Peter Maydell @ 2019-06-10 13:45 UTC (permalink / raw)
To: qemu-devel; +Cc: Paolo Bonzini, John Snow, Michael Roth
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>
---
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 <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 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"
+
# -- 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..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).
+
+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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST
2019-06-10 13:45 [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST Peter Maydell
@ 2019-06-10 13:56 ` Paolo Bonzini
2019-06-10 14:11 ` Peter Maydell
2019-06-10 14:56 ` Peter Maydell
2019-06-13 15:19 ` Michael Roth
2 siblings, 1 reply; 7+ messages in thread
From: Paolo Bonzini @ 2019-06-10 13:56 UTC (permalink / raw)
To: Peter Maydell, qemu-devel; +Cc: John Snow, Michael Roth
On 10/06/19 15:45, Peter Maydell wrote:
> +# 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")
...
> +# 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")
This should be /usr/local/etc/qemu is you want $(qemu_confdir) above and
not $(sysconfdir).
But since we always set the variable when building from the QEMU build
system, perhaps "/etc" or "/etc/qemu" is a more useful default when
building the manual outside QEMU?
Paolo
> +rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
> +
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST
2019-06-10 13:56 ` Paolo Bonzini
@ 2019-06-10 14:11 ` Peter Maydell
0 siblings, 0 replies; 7+ messages in thread
From: Peter Maydell @ 2019-06-10 14:11 UTC (permalink / raw)
To: Paolo Bonzini; +Cc: John Snow, QEMU Developers, Michael Roth
On Mon, 10 Jun 2019 at 14:56, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> On 10/06/19 15:45, Peter Maydell wrote:
> > +# 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")
>
>
> ...
>
> > +# 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")
>
> This should be /usr/local/etc/qemu is you want $(qemu_confdir) above and
> not $(sysconfdir).
>
> But since we always set the variable when building from the QEMU build
> system, perhaps "/etc" or "/etc/qemu" is a more useful default when
> building the manual outside QEMU?
Yeah, I wasn't sure what to set this to either...
thanks
-- PMM
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST
2019-06-10 13:45 [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST Peter Maydell
2019-06-10 13:56 ` Paolo Bonzini
@ 2019-06-10 14:56 ` Peter Maydell
2019-06-13 15:19 ` Michael Roth
2 siblings, 0 replies; 7+ messages in thread
From: Peter Maydell @ 2019-06-10 14:56 UTC (permalink / raw)
To: QEMU Developers; +Cc: Paolo Bonzini, John Snow, Michael Roth
On Mon, 10 Jun 2019 at 14:45, 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>
> ---
> 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
I just realised that I forgot to update the Makefile 'install-manual'
macro to filter out the generated docs/interop/qemu-ga.8 file,
so at the moment 'make install' will put a copy into
/usr/local/share/doc/qemu/interop/ as well as into
/usr/local/share/man/man8/. I'll fix that in v2.
thanks
-- PMM
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST
2019-06-10 13:45 [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST Peter Maydell
2019-06-10 13:56 ` Paolo Bonzini
2019-06-10 14:56 ` Peter Maydell
@ 2019-06-13 15:19 ` Michael Roth
2019-06-13 15:29 ` Peter Maydell
2 siblings, 1 reply; 7+ messages in thread
From: Michael Roth @ 2019-06-13 15:19 UTC (permalink / raw)
To: Peter Maydell, qemu-devel; +Cc: Paolo Bonzini, John Snow
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.maydell@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 <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 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 <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..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!)
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST
2019-06-13 15:19 ` Michael Roth
@ 2019-06-13 15:29 ` Peter Maydell
2019-06-13 16:51 ` Michael Roth
0 siblings, 1 reply; 7+ messages in thread
From: Peter Maydell @ 2019-06-13 15:29 UTC (permalink / raw)
To: Michael Roth; +Cc: Paolo Bonzini, John Snow, QEMU Developers
On Thu, 13 Jun 2019 at 16:20, Michael Roth <mdroth@linux.vnet.ibm.com> wrote:
>
> 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.maydell@linaro.org>
> > +# 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")
> > --- 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?
No, if you're invoking Sphinx via the makefile then we should
be passing CONFDIR="$(qemu_confdir)" to set the environment
variable when we invoke it. Can you try doing a build with V=1
to check the sphinx command line ?
I've just realized that I didn't also update the 'build-manual'
macro to add the CONFDIR setting. Perhaps Sphinx ran first with
the build-manual macro and has cached document contents created
with that incorrect invocation and then reused them in the manpage
creation? If so, this should be fixable by adding the CONFDIR="$(qemu_confdir)"
to the build-manual macro in the Makefile, and then deleting the .doctrees/
directory from your build tree and rerunning make.
> 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
Sure; I'll change this in v2.
thanks
-- PMM
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST
2019-06-13 15:29 ` Peter Maydell
@ 2019-06-13 16:51 ` Michael Roth
0 siblings, 0 replies; 7+ messages in thread
From: Michael Roth @ 2019-06-13 16:51 UTC (permalink / raw)
To: Peter Maydell; +Cc: Paolo Bonzini, John Snow, QEMU Developers
Quoting Peter Maydell (2019-06-13 10:29:33)
> On Thu, 13 Jun 2019 at 16:20, Michael Roth <mdroth@linux.vnet.ibm.com> wrote:
> >
> > 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.maydell@linaro.org>
>
> > > +# 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")
>
> > > --- 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?
>
> No, if you're invoking Sphinx via the makefile then we should
> be passing CONFDIR="$(qemu_confdir)" to set the environment
> variable when we invoke it. Can you try doing a build with V=1
> to check the sphinx command line ?
Here's the relevant output from make. The environment variable seems to
be defined as expected but I guess sphinx-build isn't picking it up for
some reason?
( echo "@set VERSION 4.0.50" && echo "@set CONFDIR /home/mdroth/w/qemu-install2/etc/qemu" )> docs/version.texi
sh /home/mdroth/w/qemu4.git/scripts/hxtool -t < /home/mdroth/w/qemu4.git/qemu-options.hx > qemu-options.texi
sh /home/mdroth/w/qemu4.git/scripts/hxtool -t < /home/mdroth/w/qemu4.git/hmp-commands.hx > qemu-monitor.texi
sh /home/mdroth/w/qemu4.git/scripts/hxtool -t < /home/mdroth/w/qemu4.git/qemu-img-cmds.hx > qemu-img-cmds.texi
sh /home/mdroth/w/qemu4.git/scripts/hxtool -t < /home/mdroth/w/qemu4.git/hmp-commands-info.hx > qemu-monitor-info.texi
LC_ALL=C makeinfo --no-split --number-sections -I docs -I /home/mdroth/w/qemu4.git -I . --no-headers --html /home/mdroth/w/qemu4.git/qemu-doc.texi -o qemu-doc.html
LC_ALL=C makeinfo --no-split --number-sections -I docs -I /home/mdroth/w/qemu4.git -I . --no-headers --plaintext /home/mdroth/w/qemu4.git/qemu-doc.texi -o qemu-doc.txt
perl -Ww -- /home/mdroth/w/qemu4.git/scripts/texi2pod.pl -I docs -I /home/mdroth/w/qemu4.git -I . -DVERSION="4.0.50" -DCONFDIR="/home/mdroth/w/qemu-install2/etc/qemu" /home/mdroth/w/qemu4.git/qemu-doc.texi qemu.1.pod && pod2man --utf8 --section=1 --center=" " --release=" " qemu.1.pod > qemu.1
perl -Ww -- /home/mdroth/w/qemu4.git/scripts/texi2pod.pl -I docs -I /home/mdroth/w/qemu4.git -I . -DVERSION="4.0.50" -DCONFDIR="/home/mdroth/w/qemu-install2/etc/qemu" /home/mdroth/w/qemu4.git/qemu-img.texi qemu-img.1.pod && pod2man --utf8 --section=1 --center=" " --release=" " qemu-img.1.pod > qemu-img.1
perl -Ww -- /home/mdroth/w/qemu4.git/scripts/texi2pod.pl -I docs -I /home/mdroth/w/qemu4.git -I . -DVERSION="4.0.50" -DCONFDIR="/home/mdroth/w/qemu-install2/etc/qemu" /home/mdroth/w/qemu4.git/qemu-nbd.texi qemu-nbd.8.pod && pod2man --utf8 --section=8 --center=" " --release=" " qemu-nbd.8.pod > qemu-nbd.8
CONFDIR="/home/mdroth/w/qemu-install2/etc/qemu" sphinx-build -W -n -b man -D version=4.0.50 -D release="4.0.50 (v4.0.0-1240-g90b8a170d2-dirty)" -d .doctrees/interop /home/mdroth/w/qemu4.git/docs/interop docs/interop
Running Sphinx v1.6.7
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [config changed] 7 added, 0 changed, 0 removed
reading sources... [ 14%] bitmaps
reading sources... [ 28%] index
reading sources... [ 42%] live-block-operations
reading sources... [ 57%] pr-helper
reading sources... [ 71%] qemu-ga
reading sources... [ 85%] vhost-user
reading sources... [100%] vhost-user-gpu
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... qemu-ga.8 { }
build succeeded.
>
> I've just realized that I didn't also update the 'build-manual'
> macro to add the CONFDIR setting. Perhaps Sphinx ran first with
> the build-manual macro and has cached document contents created
> with that incorrect invocation and then reused them in the manpage
> creation? If so, this should be fixable by adding the CONFDIR="$(qemu_confdir)"
> to the build-manual macro in the Makefile, and then deleting the .doctrees/
> directory from your build tree and rerunning make.
Sorry looks like it was an issue on my end actually...I guess I had a left-over
.doctrees from an earlier build (with no --prefix). I generally rm -rf * within
build directory instead of 'make clean', but that was still leaving around a
stale .doctrees. Once I deleted that I could no longer reproduce (neither
with/without the additional CONFDIR setting).
>
> > 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
>
> Sure; I'll change this in v2.
>
> thanks
> -- PMM
>
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2019-06-13 18:14 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-06-10 13:45 [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST Peter Maydell
2019-06-10 13:56 ` Paolo Bonzini
2019-06-10 14:11 ` Peter Maydell
2019-06-10 14:56 ` Peter Maydell
2019-06-13 15:19 ` Michael Roth
2019-06-13 15:29 ` Peter Maydell
2019-06-13 16:51 ` Michael Roth
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.