diff --git a/Makefile b/Makefile index 15f8e53d05..aa9cc0b584 100644 --- a/Makefile +++ b/Makefile @@ -345,11 +345,11 @@ endif ifdef BUILD_DOCS 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)/tools/qemu-img.1 +DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-nbd.8 DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8 ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy) -DOCS+=$(MANUAL_BUILDDIR)/interop/virtiofsd.1 +DOCS+=$(MANUAL_BUILDDIR)/tools/virtiofsd.1 endif DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7 @@ -357,10 +357,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+=$(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1 +DOCS+=$(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1 endif ifdef CONFIG_TRACE_SYSTEMTAP -DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1 +DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-trace-stap.1 endif else DOCS= @@ -786,6 +786,7 @@ distclean: clean $(call clean-manual,interop) $(call clean-manual,specs) $(call clean-manual,system) + $(call clean-manual,tools) for d in $(TARGET_DIRS); do \ rm -rf $$d || exit 1 ; \ done @@ -843,6 +844,7 @@ install-sphinxdocs: sphinxdocs $(call install-manual,interop) $(call install-manual,specs) $(call install-manual,system) + $(call install-manual,tools) install-doc: $(DOCS) install-sphinxdocs $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" @@ -859,12 +861,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) $(MANUAL_BUILDDIR)/interop/qemu-img.1 "$(DESTDIR)$(mandir)/man1" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-img.1 "$(DESTDIR)$(mandir)/man1" $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8" - $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8" endif ifdef CONFIG_TRACE_SYSTEMTAP - $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1" endif ifneq (,$(findstring qemu-ga,$(TOOLS))) $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8" @@ -875,10 +877,10 @@ endif endif ifdef CONFIG_VIRTFS $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" - $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1" endif ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy) - $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/virtiofsd.1 "$(DESTDIR)$(mandir)/man1" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/virtiofsd.1 "$(DESTDIR)$(mandir)/man1" endif install-datadir: @@ -1036,7 +1038,8 @@ 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 \ - $(MANUAL_BUILDDIR)/system/index.html + $(MANUAL_BUILDDIR)/system/index.html \ + $(MANUAL_BUILDDIR)/tools/index.html # Canned command to build a single manual # Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man') @@ -1046,7 +1049,6 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \ 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) \ - $(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]) @@ -1060,7 +1062,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(call build-manual,interop,html) $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1069,13 +1071,18 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) $(call build-manual,system,html) -$(call define-manpage-rule,interop,\ - qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\ - virtiofsd.1 virtfs-proxy-helper.1,\ - $(SRC_PATH)/qemu-img-cmds.hx) +$(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc + $(call build-manual,tools,html) + +$(call define-manpage-rule,interop,qemu-ga.8) $(call define-manpage-rule,system,qemu-block-drivers.7) +$(call define-manpage-rule,tools,\ + qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\ + virtiofsd.1 virtfs-proxy-helper.1,\ + $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc) + $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h @mkdir -p "$(MANUAL_BUILDDIR)" $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \ diff --git a/docs/index.html.in b/docs/index.html.in index 8512933d14..cf61b1cf44 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -13,6 +13,7 @@
  • System Emulation Management and Interoperability Guide
  • System Emulation Guest Hardware Specifications
  • System Emulation User's Guide
    • +
  • Tools Guide
    • diff --git a/docs/index.rst b/docs/index.rst index 46405d4f07..acd604fa8a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,3 +14,4 @@ Welcome to QEMU's documentation! devel/index specs/index system/index + tools/index diff --git a/docs/interop/conf.py b/docs/interop/conf.py index b3cda17042..42ce7e3d36 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -19,16 +19,4 @@ html_theme_options['description'] = u'System Emulation Management and Interopera man_pages = [ ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent', ['Michael Roth '], 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 '], 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), - ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system daemon', - ['Stefan Hajnoczi ', - 'Masayoshi Mizuma '], 1), ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index e8455b4270..049387ac6d 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -18,10 +18,5 @@ Contents: live-block-operations pr-helper qemu-ga - qemu-img - qemu-nbd - qemu-trace-stap vhost-user vhost-user-gpu - virtfs-proxy-helper - virtiofsd diff --git a/docs/interop/qemu-option-trace.rst.inc b/docs/qemu-option-trace.rst.inc similarity index 100% rename from docs/interop/qemu-option-trace.rst.inc rename to docs/qemu-option-trace.rst.inc diff --git a/docs/tools/conf.py b/docs/tools/conf.py new file mode 100644 index 0000000000..9052d17d6d --- /dev/null +++ b/docs/tools/conf.py @@ -0,0 +1,33 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file for the 'tools' manual. +# +# This includes the top level conf file and then makes any necessary tweaks. +import sys +import os + +qemu_docdir = os.path.abspath("..") +parent_config = os.path.join(qemu_docdir, "conf.py") +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'Tools Guide' + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('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 '], 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), + ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system daemon', + ['Stefan Hajnoczi ', + 'Masayoshi Mizuma '], 1), +] diff --git a/docs/tools/index.rst b/docs/tools/index.rst new file mode 100644 index 0000000000..232ce9f3e4 --- /dev/null +++ b/docs/tools/index.rst @@ -0,0 +1,17 @@ +.. This is the top level page for the 'tools' manual + + +QEMU Tools Guide +================ + + +Contents: + +.. toctree:: + :maxdepth: 2 + + qemu-img + qemu-nbd + qemu-trace-stap + virtfs-proxy-helper + virtiofsd diff --git a/docs/interop/qemu-img.rst b/docs/tools/qemu-img.rst similarity index 99% rename from docs/interop/qemu-img.rst rename to docs/tools/qemu-img.rst index 5f40137c10..0080f83a76 100644 --- a/docs/interop/qemu-img.rst +++ b/docs/tools/qemu-img.rst @@ -34,7 +34,7 @@ Standard options: .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] - .. include:: qemu-option-trace.rst.inc + .. include:: ../qemu-option-trace.rst.inc The following commands are supported: diff --git a/docs/interop/qemu-nbd.rst b/docs/tools/qemu-nbd.rst similarity index 99% rename from docs/interop/qemu-nbd.rst rename to docs/tools/qemu-nbd.rst index e548403100..667861cb22 100644 --- a/docs/interop/qemu-nbd.rst +++ b/docs/tools/qemu-nbd.rst @@ -188,7 +188,7 @@ driver options if ``--image-opts`` is specified. .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] - .. include:: qemu-option-trace.rst.inc + .. include:: ../qemu-option-trace.rst.inc Examples -------- diff --git a/docs/interop/qemu-trace-stap.rst b/docs/tools/qemu-trace-stap.rst similarity index 100% rename from docs/interop/qemu-trace-stap.rst rename to docs/tools/qemu-trace-stap.rst diff --git a/docs/interop/virtfs-proxy-helper.rst b/docs/tools/virtfs-proxy-helper.rst similarity index 100% rename from docs/interop/virtfs-proxy-helper.rst rename to docs/tools/virtfs-proxy-helper.rst diff --git a/docs/interop/virtiofsd.rst b/docs/tools/virtiofsd.rst similarity index 100% rename from docs/interop/virtiofsd.rst rename to docs/tools/virtiofsd.rst