Commit 27a296fc authored by Peter Maydell's avatar Peter Maydell
Browse files

qemu-ga: Convert invocation documentation to rST 



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: default avatarPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: default avatarMichael Roth <mdroth@linux.vnet.ibm.com>
Tested-by: default avatarMichael Roth <mdroth@linux.vnet.ibm.com>
Message-id: 20190905131040.8350-1-peter.maydell@linaro.org
parent d2fac5f6

MAINTAINERS

+1 −1
Original line number Diff line number Diff line
@@ -2040,7 +2040,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

Makefile

+14 −10
Original line number Diff line number Diff line
@@ -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
@@ -783,10 +783,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
@@ -818,7 +819,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"
@@ -977,18 +978,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","$@")
@@ -1013,7 +1018,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
@@ -1026,7 +1030,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

docs/conf.py

+10 −8
Original line number Diff line number Diff line
@@ -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 -------------------------------------------

docs/interop/conf.py

+7 −0
Original line number Diff line number Diff line
@@ -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)

]

docs/interop/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -15,5 +15,6 @@ Contents: 
   bitmaps

   live-block-operations

   pr-helper

   qemu-ga

   vhost-user

   vhost-user-gpu