Commit f31160c7 authored by Peter Maydell's avatar Peter Maydell
Browse files

Merge remote-tracking branch 'remotes/pmaydell/tags/pull-docs-20200203' into staging 



docs:
 * Fix Makefile concurrency bug where we could run Sphinx twice
   in parallel on the same manual (which makes it crash)
 * Support handling hxtool doc fragments for rST manuals
 * Convert qemu-img docs to rST
 * Convert qemu-trace-stap docs to rST
 * Convert virtfs-proxy-helper docs to rST

# gpg: Signature made Mon 03 Feb 2020 11:11:44 GMT
# gpg:                using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg:                issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@gmail.com>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83  15CF 3C25 25ED 1436 0CDE

* remotes/pmaydell/tags/pull-docs-20200203:
  virtfs-proxy-helper: Convert documentation to rST
  scripts/qemu-trace-stap: Convert documentation to rST
  qemu-img-cmds.hx: Remove texinfo document fragments
  qemu-img: Convert invocation documentation to rST
  qemu-img-cmds.hx: Add rST documentation fragments
  docs/sphinx: Add new hxtool Sphinx extension
  hxtool: Support SRST/ERST directives
  Makefile: Ensure we don't run Sphinx in parallel for manpages

Signed-off-by: default avatarPeter Maydell <peter.maydell@linaro.org>
parents 035b2197 78813586

MAINTAINERS

+3 −0
Original line number Diff line number Diff line
@@ -1574,6 +1574,7 @@ S: Odd Fixes 
F: hw/9pfs/

X: hw/9pfs/xen-9p*

F: fsdev/

F: docs/interop/virtfs-proxy-helper.rst

F: tests/qtest/virtio-9p-test.c

T: git https://github.com/gkurz/qemu.git 9p-next
@@ -1834,6 +1835,7 @@ F: block/ 
F: hw/block/

F: include/block/

F: qemu-img*

F: docs/interop/qemu-img.rst

F: qemu-io*

F: tests/qemu-iotests/

F: util/qemu-progress.c
@@ -2192,6 +2194,7 @@ F: qemu-option-trace.texi 
F: scripts/tracetool.py

F: scripts/tracetool/

F: scripts/qemu-trace-stap*

F: docs/interop/qemu-trace-stap.rst

F: docs/devel/tracing.txt

T: git https://github.com/stefanha/qemu.git tracing

Makefile

+23 −23
Original line number Diff line number Diff line
@@ -344,7 +344,8 @@ MANUAL_BUILDDIR := docs 
endif



ifdef BUILD_DOCS

DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1

DOCS=qemu-doc.html qemu-doc.txt qemu.1

DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-img.1

DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8

DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8

DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
@@ -353,10 +354,10 @@ DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qe 
DOCS+=docs/qemu-cpu-models.7

DOCS+=$(MANUAL_BUILDDIR)/index.html

ifdef CONFIG_VIRTFS

DOCS+=fsdev/virtfs-proxy-helper.1

DOCS+=$(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1

endif

ifdef CONFIG_TRACE_SYSTEMTAP

DOCS+=scripts/qemu-trace-stap.1

DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1

endif

else

DOCS=
@@ -744,7 +745,7 @@ rm -f $(MANUAL_BUILDDIR)/$1/objects.inv $(MANUAL_BUILDDIR)/$1/searchindex.js $(M 
endef



distclean: clean

	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi

	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi

	rm -f tests/tcg/config-*.mak

	rm -f config-all-devices.mak config-all-disas.mak config.status

	rm -f $(SUBDIR_DEVICES_MAK)
@@ -842,12 +843,12 @@ ifdef CONFIG_POSIX 
	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"

	$(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"

ifeq ($(CONFIG_TOOLS),y)

	$(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"

	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-img.1 "$(DESTDIR)$(mandir)/man1"

	$(INSTALL_DIR) "$(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"

	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"

endif

ifneq (,$(findstring qemu-ga,$(TOOLS)))

	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
@@ -858,7 +859,7 @@ endif 
endif

ifdef CONFIG_VIRTFS

	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"

	$(INSTALL_DATA) fsdev/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"

	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"

endif



install-datadir:
@@ -1028,11 +1029,19 @@ build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if 
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

# Macro to write out the rule and dependencies for building manpages

# Usage: $(call define-manpage-rule,manualname,manpage1 manpage2...[,extradeps])

# 'extradeps' is optional, and specifies extra files (eg .hx files) that

# the manual page depends on.

define define-manpage-rule

$(call atomic,$(foreach manpage,$2,$(MANUAL_BUILDDIR)/$1/$(manpage)),$(call manual-deps,$1) $3)

	$(call build-manual,$1,man)

endef



$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)

	$(call build-manual,devel,html)



$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)

$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx

	$(call build-manual,interop,html)



$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
@@ -1041,14 +1050,11 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) 
$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)

	$(call build-manual,system,html)



$(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)

$(call define-manpage-rule,interop,\

       qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1 virtfs-proxy-helper.1,\

       $(SRC_PATH/qemu-img-cmds.hx))



$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7: $(call manual-deps,system)

	$(call build-manual,system,man)

$(call define-manpage-rule,system,qemu-block-drivers.7)



$(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h

	@mkdir -p "$(MANUAL_BUILDDIR)"
@@ -1064,9 +1070,6 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/scripts/hxtool 
qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxtool

	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")



qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/scripts/hxtool

	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")



docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi

	@cp -p $< $@
@@ -1075,10 +1078,7 @@ docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi 


qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi

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

docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi

scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi



html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs

info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
@@ -1086,9 +1086,9 @@ pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf 
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-options.texi \

	qemu-options.texi \

	qemu-tech.texi qemu-option-trace.texi \

	qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \

	qemu-deprecated.texi qemu-monitor.texi \

	qemu-monitor-info.texi \

	docs/qemu-cpu-models.texi docs/security.texi

docs/conf.py

+2 −1
Original line number Diff line number Diff line
@@ -54,7 +54,7 @@ needs_sphinx = '1.3' 
# Add any Sphinx extension module names here, as strings. They can be

# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

# ones.

extensions = ['kerneldoc', 'qmp_lexer']

extensions = ['kerneldoc', 'qmp_lexer', 'hxtool']



# Add any paths that contain templates here, relative to this directory.

templates_path = ['_templates']
@@ -221,3 +221,4 @@ texinfo_documents = [ 
# find everything.

kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc')

kerneldoc_srctree = os.path.join(qemu_docdir, '..')

hxtool_srctree = os.path.join(qemu_docdir, '..')

docs/interop/conf.py

+8 −1
Original line number Diff line number Diff line
@@ -19,6 +19,13 @@ html_theme_options['description'] = u'System Emulation Management and Interopera 
man_pages = [

    ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',

     ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),

    ('qemu-img', 'qemu-img', u'QEMU disk image utility',

     ['Fabrice Bellard'], 1),

    ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',

     ['Anthony Liguori <anthony@codemonkey.ws>'], 8)

     ['Anthony Liguori <anthony@codemonkey.ws>'], 8),

    ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',

     [], 1),

    ('virtfs-proxy-helper', 'virtfs-proxy-helper',

     u'QEMU 9p virtfs proxy filesystem helper',

     ['M. Mohan Kumar'], 1)

]

docs/interop/index.rst

+3 −0
Original line number Diff line number Diff line
@@ -18,6 +18,9 @@ Contents: 
   live-block-operations

   pr-helper

   qemu-ga

   qemu-img

   qemu-nbd

   qemu-trace-stap

   vhost-user

   vhost-user-gpu

   virtfs-proxy-helper