Re: [PATCH 1/3] qemu-nbd: Convert invocation documentation to rST
On Thu, 23 Jan 2020 at 12:43, Eric Blake wrote: > > On 1/16/20 8:15 AM, Peter Maydell wrote: > > The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo > > format, which we present to the user as: > > * a qemu-nbd 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-nbd manpage > > * part of the interop/ Sphinx manual > > > > As I have now posted a patch that conflicts with this > (https://lists.gnu.org/archive/html/qemu-devel/2020-01/msg05118.html), > and it needs a v2, I'm happy to do my rebase on top of this series, and > stage these patches through my NBD tree if they don't land on master > sooner via another path. Since they've now been reviewed, I propose to put them in via an arm pullreq I'm going to make either today or tomorrow. thanks -- PMM
Re: [PATCH 1/3] qemu-nbd: Convert invocation documentation to rST
On 1/16/20 8:15 AM, Peter Maydell wrote: The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo format, which we present to the user as: * a qemu-nbd 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-nbd manpage * part of the interop/ Sphinx manual As I have now posted a patch that conflicts with this (https://lists.gnu.org/archive/html/qemu-devel/2020-01/msg05118.html), and it needs a v2, I'm happy to do my rebase on top of this series, and stage these patches through my NBD tree if they don't land on master sooner via another path. v1->v2: * avoided some long lines in the Makefile --- Makefile | 16 +- MAINTAINERS| 1 + docs/interop/conf.py | 4 +- docs/interop/index.rst | 1 + docs/interop/qemu-nbd.rst | 263 + docs/interop/qemu-option-trace.rst.inc | 30 +++ qemu-doc.texi | 6 - qemu-nbd.texi | 214 qemu-option-trace.texi | 4 + 9 files changed, 313 insertions(+), 226 deletions(-) create mode 100644 docs/interop/qemu-nbd.rst create mode 100644 docs/interop/qemu-option-trace.rst.inc delete mode 100644 qemu-nbd.texi Reviewed-by: Eric Blake -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
Re: [PATCH 1/3] qemu-nbd: Convert invocation documentation to rST
Peter Maydell writes:
> The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo
> format, which we present to the user as:
> * a qemu-nbd 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-nbd manpage
> * part of the interop/ Sphinx manual
>
> This follows the same pattern as commit 27a296fce982 did for the
> qemu-ga manpage.
>
> All the content of the old manpage is retained, except that I have
> dropped the "This is free software; see the source for copying
> conditions. There is NO warranty..." text that was in the old AUTHOR
> section; Sphinx's manpage builder doesn't expect that much text in
> the AUTHOR section, and since none of our other manpages have it it
> seems easiest to delete it rather than try to figure out where else
> in the manpage to put it.
>
> The only other textual change is that I have had to give the
> --nocache option its own description ("Equivalent to --cache=none")
> because Sphinx doesn't have an equivalent of using item/itemx
> to share a description between two options.
>
> Some minor aspects of the formatting have changed, to suit what is
> easiest for Sphinx to output. (The most notable is that Sphinx
> option section option syntax doesn't support '--option foo=bar'
> with bar underlined rather than bold, so we have to switch to
> '--option foo=BAR' instead.)
>
> The contents of qemu-option-trace.texi are now duplicated in
> docs/interop/qemu-option-trace.rst.inc, until such time as we complete
> the conversion of the other files which use it; since it has had only
> 3 changes in 3 years, this shouldn't be too awkward a burden.
> (We use .rst.inc because if this file fragment has a .rst extension
> then Sphinx complains about not seeing it in a toctree.)
>
> Signed-off-by: Peter Maydell
Reviewed-by: Alex Bennée
Tested-by: Alex Bennée
> ---
> Another step forward for https://wiki.qemu.org/Features/Documentation
> (this is part of step 3 in the 'transition plan').
>
> v1->v2:
> * avoided some long lines in the Makefile
> ---
> Makefile | 16 +-
> MAINTAINERS| 1 +
> docs/interop/conf.py | 4 +-
> docs/interop/index.rst | 1 +
> docs/interop/qemu-nbd.rst | 263 +
> docs/interop/qemu-option-trace.rst.inc | 30 +++
> qemu-doc.texi | 6 -
> qemu-nbd.texi | 214
> qemu-option-trace.texi | 4 +
> 9 files changed, 313 insertions(+), 226 deletions(-)
> create mode 100644 docs/interop/qemu-nbd.rst
> create mode 100644 docs/interop/qemu-option-trace.rst.inc
> delete mode 100644 qemu-nbd.texi
>
> diff --git a/Makefile b/Makefile
> index afa5cb6548d..7a8a50d8700 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -339,7 +339,9 @@ MANUAL_BUILDDIR := docs
> endif
>
> ifdef BUILD_DOCS
> -DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8
> $(MANUAL_BUILDDIR)/interop/qemu-ga.8
> +DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1
> +DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8
> +DOCS+=$(MANUAL_BUILDDIR)/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
> @@ -829,7 +831,7 @@ ifdef CONFIG_POSIX
> ifeq ($(CONFIG_TOOLS),y)
> $(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"
> $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
> - $(INSTALL_DATA) qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
> + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8
> "$(DESTDIR)$(mandir)/man8"
> endif
> ifdef CONFIG_TRACE_SYSTEMTAP
> $(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
> @@ -1007,7 +1009,9 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html
> $(MANUAL_BUILDDIR)/interop/index
> # a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946
> build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build
> $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d
> .doctrees/$1-$2 $(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-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \
> + $(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \
> + $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
>
> $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)
> $(call build-manual,devel,html)
> @@ -1021,6 +1025,9 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call
> manual-deps,specs)
> $(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call
[PATCH 1/3] qemu-nbd: Convert invocation documentation to rST
The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo
format, which we present to the user as:
* a qemu-nbd 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-nbd manpage
* part of the interop/ Sphinx manual
This follows the same pattern as commit 27a296fce982 did for the
qemu-ga manpage.
All the content of the old manpage is retained, except that I have
dropped the "This is free software; see the source for copying
conditions. There is NO warranty..." text that was in the old AUTHOR
section; Sphinx's manpage builder doesn't expect that much text in
the AUTHOR section, and since none of our other manpages have it it
seems easiest to delete it rather than try to figure out where else
in the manpage to put it.
The only other textual change is that I have had to give the
--nocache option its own description ("Equivalent to --cache=none")
because Sphinx doesn't have an equivalent of using item/itemx
to share a description between two options.
Some minor aspects of the formatting have changed, to suit what is
easiest for Sphinx to output. (The most notable is that Sphinx
option section option syntax doesn't support '--option foo=bar'
with bar underlined rather than bold, so we have to switch to
'--option foo=BAR' instead.)
The contents of qemu-option-trace.texi are now duplicated in
docs/interop/qemu-option-trace.rst.inc, until such time as we complete
the conversion of the other files which use it; since it has had only
3 changes in 3 years, this shouldn't be too awkward a burden.
(We use .rst.inc because if this file fragment has a .rst extension
then Sphinx complains about not seeing it in a toctree.)
Signed-off-by: Peter Maydell
---
Another step forward for https://wiki.qemu.org/Features/Documentation
(this is part of step 3 in the 'transition plan').
v1->v2:
* avoided some long lines in the Makefile
---
Makefile | 16 +-
MAINTAINERS| 1 +
docs/interop/conf.py | 4 +-
docs/interop/index.rst | 1 +
docs/interop/qemu-nbd.rst | 263 +
docs/interop/qemu-option-trace.rst.inc | 30 +++
qemu-doc.texi | 6 -
qemu-nbd.texi | 214
qemu-option-trace.texi | 4 +
9 files changed, 313 insertions(+), 226 deletions(-)
create mode 100644 docs/interop/qemu-nbd.rst
create mode 100644 docs/interop/qemu-option-trace.rst.inc
delete mode 100644 qemu-nbd.texi
diff --git a/Makefile b/Makefile
index afa5cb6548d..7a8a50d8700 100644
--- a/Makefile
+++ b/Makefile
@@ -339,7 +339,9 @@ MANUAL_BUILDDIR := docs
endif
ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8
$(MANUAL_BUILDDIR)/interop/qemu-ga.8
+DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1
+DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8
+DOCS+=$(MANUAL_BUILDDIR)/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
@@ -829,7 +831,7 @@ ifdef CONFIG_POSIX
ifeq ($(CONFIG_TOOLS),y)
$(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
- $(INSTALL_DATA) qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
+ $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8
"$(DESTDIR)$(mandir)/man8"
endif
ifdef CONFIG_TRACE_SYSTEMTAP
$(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
@@ -1007,7 +1009,9 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html
$(MANUAL_BUILDDIR)/interop/index
# a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946
build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build
$(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d
.doctrees/$1-$2 $(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-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \
+ $(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \
+ $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)
$(call build-manual,devel,html)
@@ -1021,6 +1025,9 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call
manual-deps,specs)
$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)
$(call build-manual,interop,man)
+$(MANUAL_BUILDDIR)/interop/qemu-nbd.8: $(call manual-deps,interop)
+ $(call build-manual,interop,man)
+
$(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
$(call
