[PATCH 0/3] docs: Create a 'tools' manual

qemu-devel.nongnu.org archive mirror
 help / color / mirror / Atom feed

* [PATCH 0/3] docs: Create a 'tools' manual
@ 2020-02-17 15:54 Peter Maydell
  2020-02-17 15:54 ` [PATCH 1/3] docs: Create new " Peter Maydell
                   ` (4 more replies)
  0 siblings, 5 replies; 11+ messages in thread
From: Peter Maydell @ 2020-02-17 15:54 UTC (permalink / raw)
  To: qemu-devel
  Cc: Paolo Bonzini, Daniel P. Berrange, Dr. David Alan Gilbert,
	Stefan Hajnoczi

This patchset creates the new 'tools' manual that we've
decided we should have, and moves 5 existing documents to it:

 docs/interop/qemu-img.rst
 docs/interop/qemu-nbd.rst
 docs/interop/virtfs-proxy-helper.rst
 docs/interop/qemu-trace-stap.rst
 docs/interop/virtiofsd.rst

This change will conflict with the QAPI-doc-comment-to-rST
patchset because they both change the docs/interop makefile
rules, but I expect this one to get in to master first;
the other needs a respin at some point anyhow.

thanks
-- PMM

Peter Maydell (3):
  docs: Create new 'tools' manual
  docs: Move qemu-option-trace.rst.inc to docs/
  docs: Move tools documentation to tools manual

 Makefile                                      | 41 +++++++++++--------
 docs/index.html.in                            |  1 +
 docs/index.rst                                |  1 +
 docs/interop/conf.py                          | 12 ------
 docs/interop/index.rst                        |  5 ---
 docs/{interop => }/qemu-option-trace.rst.inc  |  0
 docs/{interop => tools}/conf.py               |  7 ++--
 docs/tools/index.rst                          | 17 ++++++++
 docs/{interop => tools}/qemu-img.rst          |  2 +-
 docs/{interop => tools}/qemu-nbd.rst          |  2 +-
 docs/{interop => tools}/qemu-trace-stap.rst   |  0
 .../virtfs-proxy-helper.rst                   |  0
 docs/{interop => tools}/virtiofsd.rst         |  0
 13 files changed, 48 insertions(+), 40 deletions(-)
 rename docs/{interop => }/qemu-option-trace.rst.inc (100%)
 copy docs/{interop => tools}/conf.py (80%)
 create mode 100644 docs/tools/index.rst
 rename docs/{interop => tools}/qemu-img.rst (99%)
 rename docs/{interop => tools}/qemu-nbd.rst (99%)
 rename docs/{interop => tools}/qemu-trace-stap.rst (100%)
 rename docs/{interop => tools}/virtfs-proxy-helper.rst (100%)
 rename docs/{interop => tools}/virtiofsd.rst (100%)

-- 
2.20.1



^ permalink raw reply	[flat|nested] 11+ messages in thread

* [PATCH 1/3] docs: Create new 'tools' manual
  2020-02-17 15:54 [PATCH 0/3] docs: Create a 'tools' manual Peter Maydell
@ 2020-02-17 15:54 ` Peter Maydell
  2020-02-17 15:54 ` [PATCH 2/3] docs: Move qemu-option-trace.rst.inc to docs/ Peter Maydell
                   ` (3 subsequent siblings)
  4 siblings, 0 replies; 11+ messages in thread
From: Peter Maydell @ 2020-02-17 15:54 UTC (permalink / raw)
  To: qemu-devel
  Cc: Paolo Bonzini, Daniel P. Berrange, Dr. David Alan Gilbert,
	Stefan Hajnoczi

Some of the documentation for QEMU "tools" which are standalone
binaries like qemu-img is an awkward fit in our current 5-manual
split. We've put it into "interop", but they're not really
about interoperability.

Create a new top level manual "tools" which will be a better
home for this documentation. This commit creates an empty
initial manual; we will move the relevant documentation
files in a subsequent commit.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 Makefile             |  8 +++++++-
 docs/index.html.in   |  1 +
 docs/index.rst       |  1 +
 docs/tools/conf.py   | 16 ++++++++++++++++
 docs/tools/index.rst | 11 +++++++++++
 5 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 docs/tools/conf.py
 create mode 100644 docs/tools/index.rst

diff --git a/Makefile b/Makefile
index b5a7377cb18..ceb85f67c4b 100644
--- a/Makefile
+++ b/Makefile
@@ -773,6 +773,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
@@ -830,6 +831,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)"
@@ -1023,7 +1025,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')
@@ -1056,6 +1059,9 @@ $(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)/tools/index.html: $(call manual-deps,tools)
+	$(call build-manual,tools,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,\
diff --git a/docs/index.html.in b/docs/index.html.in
index 8512933d145..cf61b1cf448 100644
--- a/docs/index.html.in
+++ b/docs/index.html.in
@@ -13,6 +13,7 @@
             <li><a href="interop/index.html">System Emulation Management and Interoperability Guide</a></li>
             <li><a href="specs/index.html">System Emulation Guest Hardware Specifications</a></li>
             <li><a href="system/index.html">System Emulation User's Guide</a></li>
+            <li><a href="tools/index.html">Tools Guide</a></li>
         </ul>
     </body>
 </html>
diff --git a/docs/index.rst b/docs/index.rst
index 46405d4f077..acd604fa8a9 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/tools/conf.py b/docs/tools/conf.py
new file mode 100644
index 00000000000..56461110b9d
--- /dev/null
+++ b/docs/tools/conf.py
@@ -0,0 +1,16 @@
+# -*- 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'
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
new file mode 100644
index 00000000000..c5a4a13ec7a
--- /dev/null
+++ b/docs/tools/index.rst
@@ -0,0 +1,11 @@
+.. This is the top level page for the 'tools' manual
+
+
+QEMU Tools Guide
+================
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
-- 
2.20.1



^ permalink raw reply related	[flat|nested] 11+ messages in thread

* [PATCH 2/3] docs: Move qemu-option-trace.rst.inc to docs/
  2020-02-17 15:54 [PATCH 0/3] docs: Create a 'tools' manual Peter Maydell
  2020-02-17 15:54 ` [PATCH 1/3] docs: Create new " Peter Maydell
@ 2020-02-17 15:54 ` Peter Maydell
  2020-02-17 15:54 ` [PATCH 3/3] docs: Move tools documentation to tools manual Peter Maydell
                   ` (2 subsequent siblings)
  4 siblings, 0 replies; 11+ messages in thread
From: Peter Maydell @ 2020-02-17 15:54 UTC (permalink / raw)
  To: qemu-devel
  Cc: Paolo Bonzini, Daniel P. Berrange, Dr. David Alan Gilbert,
	Stefan Hajnoczi

The qemu-option-trace.rst.inc file contains a rST documentation
fragment which describes trace options common to qemu-nbd and
qemu-img.  We put this file into interop/, but we'd like to move the
qemu-nbd and qemu-img files into the tools/ manual.  We could move
the .rst.inc file along with them, but we're eventually going to want
to use it for the main QEMU binary options documentation too, and
that will be in system/.  So move qemu-option-trace.rst.inc to the
top-level docs/ directory, where all these files can include it via

   .. include:: ../qemu-option-trace.rst.inc

This does have the slight downside that we now need to explicitly
tell Make which manuals use this file rather than relying on
a wildcard for all .rst.inc in the manual.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 Makefile                                     | 5 ++---
 docs/interop/qemu-img.rst                    | 2 +-
 docs/interop/qemu-nbd.rst                    | 2 +-
 docs/{interop => }/qemu-option-trace.rst.inc | 0
 4 files changed, 4 insertions(+), 5 deletions(-)
 rename docs/{interop => }/qemu-option-trace.rst.inc (100%)

diff --git a/Makefile b/Makefile
index ceb85f67c4b..886d4299d54 100644
--- a/Makefile
+++ b/Makefile
@@ -1036,7 +1036,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])
@@ -1050,7 +1049,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) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc
 	$(call build-manual,interop,html)
 
 $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
@@ -1065,7 +1064,7 @@ $(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools)
 $(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)
+       $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc)
 
 $(call define-manpage-rule,system,qemu-block-drivers.7)
 
diff --git a/docs/interop/qemu-img.rst b/docs/interop/qemu-img.rst
index 42e4451db4a..b6cab449750 100644
--- a/docs/interop/qemu-img.rst
+++ b/docs/interop/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/interop/qemu-nbd.rst
index e5484031005..667861cb22e 100644
--- a/docs/interop/qemu-nbd.rst
+++ b/docs/interop/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-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
-- 
2.20.1



^ permalink raw reply related	[flat|nested] 11+ messages in thread

* [PATCH 3/3] docs: Move tools documentation to tools manual
  2020-02-17 15:54 [PATCH 0/3] docs: Create a 'tools' manual Peter Maydell
  2020-02-17 15:54 ` [PATCH 1/3] docs: Create new " Peter Maydell
  2020-02-17 15:54 ` [PATCH 2/3] docs: Move qemu-option-trace.rst.inc to docs/ Peter Maydell
@ 2020-02-17 15:54 ` Peter Maydell
  2020-02-17 18:24   ` Dr. David Alan Gilbert
  2020-02-17 16:00 ` [PATCH 0/3] docs: Create a 'tools' manual Richard Henderson
  2020-02-17 16:04 ` Paolo Bonzini
  4 siblings, 1 reply; 11+ messages in thread
From: Peter Maydell @ 2020-02-17 15:54 UTC (permalink / raw)
  To: qemu-devel
  Cc: Paolo Bonzini, Daniel P. Berrange, Dr. David Alan Gilbert,
	Stefan Hajnoczi

Move the following tools documentation files to the new tools manual:

 docs/interop/qemu-img.rst
 docs/interop/qemu-nbd.rst
 docs/interop/virtfs-proxy-helper.rst
 docs/interop/qemu-trace-stap.rst
 docs/interop/virtiofsd.rst

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 Makefile                                      | 34 ++++++++++---------
 docs/interop/conf.py                          | 12 -------
 docs/interop/index.rst                        |  5 ---
 docs/tools/conf.py                            | 17 ++++++++++
 docs/tools/index.rst                          |  6 ++++
 docs/{interop => tools}/qemu-img.rst          |  0
 docs/{interop => tools}/qemu-nbd.rst          |  0
 docs/{interop => tools}/qemu-trace-stap.rst   |  0
 .../virtfs-proxy-helper.rst                   |  0
 docs/{interop => tools}/virtiofsd.rst         |  0
 10 files changed, 41 insertions(+), 33 deletions(-)
 rename docs/{interop => tools}/qemu-img.rst (100%)
 rename docs/{interop => tools}/qemu-nbd.rst (100%)
 rename docs/{interop => tools}/qemu-trace-stap.rst (100%)
 rename docs/{interop => tools}/virtfs-proxy-helper.rst (100%)
 rename docs/{interop => tools}/virtiofsd.rst (100%)

diff --git a/Makefile b/Makefile
index 886d4299d54..7a9c682a2c0 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=
@@ -848,12 +848,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"
@@ -864,10 +864,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) docs/interop/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
+	$(INSTALL_DATA) docs/tools/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
 endif
 
 install-datadir:
@@ -1049,7 +1049,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 $(SRC_PATH)/docs/qemu-option-trace.rst.inc
+$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
 	$(call build-manual,interop,html)
 
 $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
@@ -1058,16 +1058,18 @@ $(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)/tools/index.html: $(call manual-deps,tools)
+$(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 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)
+$(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/interop/conf.py b/docs/interop/conf.py
index b3cda17042c..42ce7e3d365 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 <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),
-    ('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 <stefanha@redhat.com>',
-      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
 ]
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index e8455b4270c..049387ac6de 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/tools/conf.py b/docs/tools/conf.py
index 56461110b9d..9052d17d6d4 100644
--- a/docs/tools/conf.py
+++ b/docs/tools/conf.py
@@ -14,3 +14,20 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
 # 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 <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),
+    ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system daemon',
+     ['Stefan Hajnoczi <stefanha@redhat.com>',
+      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
+]
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index c5a4a13ec7a..232ce9f3e46 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -9,3 +9,9 @@ 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 100%
rename from docs/interop/qemu-img.rst
rename to docs/tools/qemu-img.rst
diff --git a/docs/interop/qemu-nbd.rst b/docs/tools/qemu-nbd.rst
similarity index 100%
rename from docs/interop/qemu-nbd.rst
rename to docs/tools/qemu-nbd.rst
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
-- 
2.20.1



^ permalink raw reply related	[flat|nested] 11+ messages in thread

* Re: [PATCH 3/3] docs: Move tools documentation to tools manual
  2020-02-17 15:54 ` [PATCH 3/3] docs: Move tools documentation to tools manual Peter Maydell
@ 2020-02-17 18:24   ` Dr. David Alan Gilbert
  2020-02-17 18:41     ` Paolo Bonzini
  0 siblings, 1 reply; 11+ messages in thread
From: Dr. David Alan Gilbert @ 2020-02-17 18:24 UTC (permalink / raw)
  To: Peter Maydell
  Cc: Paolo Bonzini, Daniel P. Berrange, qemu-devel, Stefan Hajnoczi

* Peter Maydell (peter.maydell@linaro.org) wrote:
> Move the following tools documentation files to the new tools manual:
> 
>  docs/interop/qemu-img.rst
>  docs/interop/qemu-nbd.rst
>  docs/interop/virtfs-proxy-helper.rst
>  docs/interop/qemu-trace-stap.rst
>  docs/interop/virtiofsd.rst
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Would docs/tools be the right place for the virtiofsd security guide
(as previously posted there)?  It's not actually a manpage.

Dave
> ---
>  Makefile                                      | 34 ++++++++++---------
>  docs/interop/conf.py                          | 12 -------
>  docs/interop/index.rst                        |  5 ---
>  docs/tools/conf.py                            | 17 ++++++++++
>  docs/tools/index.rst                          |  6 ++++
>  docs/{interop => tools}/qemu-img.rst          |  0
>  docs/{interop => tools}/qemu-nbd.rst          |  0
>  docs/{interop => tools}/qemu-trace-stap.rst   |  0
>  .../virtfs-proxy-helper.rst                   |  0
>  docs/{interop => tools}/virtiofsd.rst         |  0
>  10 files changed, 41 insertions(+), 33 deletions(-)
>  rename docs/{interop => tools}/qemu-img.rst (100%)
>  rename docs/{interop => tools}/qemu-nbd.rst (100%)
>  rename docs/{interop => tools}/qemu-trace-stap.rst (100%)
>  rename docs/{interop => tools}/virtfs-proxy-helper.rst (100%)
>  rename docs/{interop => tools}/virtiofsd.rst (100%)
> 
> diff --git a/Makefile b/Makefile
> index 886d4299d54..7a9c682a2c0 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=
> @@ -848,12 +848,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"
> @@ -864,10 +864,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) docs/interop/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
> +	$(INSTALL_DATA) docs/tools/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
>  endif
>  
>  install-datadir:
> @@ -1049,7 +1049,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 $(SRC_PATH)/docs/qemu-option-trace.rst.inc
> +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
>  	$(call build-manual,interop,html)
>  
>  $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
> @@ -1058,16 +1058,18 @@ $(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)/tools/index.html: $(call manual-deps,tools)
> +$(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 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)
> +$(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/interop/conf.py b/docs/interop/conf.py
> index b3cda17042c..42ce7e3d365 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 <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),
> -    ('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 <stefanha@redhat.com>',
> -      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
>  ]
> diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> index e8455b4270c..049387ac6de 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/tools/conf.py b/docs/tools/conf.py
> index 56461110b9d..9052d17d6d4 100644
> --- a/docs/tools/conf.py
> +++ b/docs/tools/conf.py
> @@ -14,3 +14,20 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
>  # 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 <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),
> +    ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system daemon',
> +     ['Stefan Hajnoczi <stefanha@redhat.com>',
> +      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
> +]
> diff --git a/docs/tools/index.rst b/docs/tools/index.rst
> index c5a4a13ec7a..232ce9f3e46 100644
> --- a/docs/tools/index.rst
> +++ b/docs/tools/index.rst
> @@ -9,3 +9,9 @@ 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 100%
> rename from docs/interop/qemu-img.rst
> rename to docs/tools/qemu-img.rst
> diff --git a/docs/interop/qemu-nbd.rst b/docs/tools/qemu-nbd.rst
> similarity index 100%
> rename from docs/interop/qemu-nbd.rst
> rename to docs/tools/qemu-nbd.rst
> 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
> -- 
> 2.20.1
> 
--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK



^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH 3/3] docs: Move tools documentation to tools manual
  2020-02-17 18:24   ` Dr. David Alan Gilbert
@ 2020-02-17 18:41     ` Paolo Bonzini
  2020-02-17 19:19       ` Peter Maydell
  0 siblings, 1 reply; 11+ messages in thread
From: Paolo Bonzini @ 2020-02-17 18:41 UTC (permalink / raw)
  To: Dr. David Alan Gilbert
  Cc: Peter Maydell, Daniel P. Berrange, qemu-devel, Stefan Hajnoczi

[-- Attachment #1: Type: text/plain, Size: 10660 bytes --]

Il lun 17 feb 2020, 19:24 Dr. David Alan Gilbert <dgilbert@redhat.com> ha
scritto:

> * Peter Maydell (peter.maydell@linaro.org) wrote:
> > Move the following tools documentation files to the new tools manual:
> >
> >  docs/interop/qemu-img.rst
> >  docs/interop/qemu-nbd.rst
> >  docs/interop/virtfs-proxy-helper.rst
> >  docs/interop/qemu-trace-stap.rst
> >  docs/interop/virtiofsd.rst
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>
> Would docs/tools be the right place for the virtiofsd security guide
> (as previously posted there)?  It's not actually a manpage.
>

Yes, I think it would.

Paolo


> Dave
> > ---
> >  Makefile                                      | 34 ++++++++++---------
> >  docs/interop/conf.py                          | 12 -------
> >  docs/interop/index.rst                        |  5 ---
> >  docs/tools/conf.py                            | 17 ++++++++++
> >  docs/tools/index.rst                          |  6 ++++
> >  docs/{interop => tools}/qemu-img.rst          |  0
> >  docs/{interop => tools}/qemu-nbd.rst          |  0
> >  docs/{interop => tools}/qemu-trace-stap.rst   |  0
> >  .../virtfs-proxy-helper.rst                   |  0
> >  docs/{interop => tools}/virtiofsd.rst         |  0
> >  10 files changed, 41 insertions(+), 33 deletions(-)
> >  rename docs/{interop => tools}/qemu-img.rst (100%)
> >  rename docs/{interop => tools}/qemu-nbd.rst (100%)
> >  rename docs/{interop => tools}/qemu-trace-stap.rst (100%)
> >  rename docs/{interop => tools}/virtfs-proxy-helper.rst (100%)
> >  rename docs/{interop => tools}/virtiofsd.rst (100%)
> >
> > diff --git a/Makefile b/Makefile
> > index 886d4299d54..7a9c682a2c0 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=
> > @@ -848,12 +848,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"
> > @@ -864,10 +864,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) docs/interop/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
> > +     $(INSTALL_DATA) docs/tools/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
> >  endif
> >
> >  install-datadir:
> > @@ -1049,7 +1049,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 $(SRC_PATH)/docs/qemu-option-trace.rst.inc
> > +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
> >       $(call build-manual,interop,html)
> >
> >  $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
> > @@ -1058,16 +1058,18 @@ $(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)/tools/index.html: $(call manual-deps,tools)
> > +$(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 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)
> > +$(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/interop/conf.py b/docs/interop/conf.py
> > index b3cda17042c..42ce7e3d365 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 <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),
> > -    ('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 <stefanha@redhat.com>',
> > -      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
> >  ]
> > diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> > index e8455b4270c..049387ac6de 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/tools/conf.py b/docs/tools/conf.py
> > index 56461110b9d..9052d17d6d4 100644
> > --- a/docs/tools/conf.py
> > +++ b/docs/tools/conf.py
> > @@ -14,3 +14,20 @@ exec(compile(open(parent_config, "rb").read(),
> parent_config, 'exec'))
> >  # 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 <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),
> > +    ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system
> daemon',
> > +     ['Stefan Hajnoczi <stefanha@redhat.com>',
> > +      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
> > +]
> > diff --git a/docs/tools/index.rst b/docs/tools/index.rst
> > index c5a4a13ec7a..232ce9f3e46 100644
> > --- a/docs/tools/index.rst
> > +++ b/docs/tools/index.rst
> > @@ -9,3 +9,9 @@ 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 100%
> > rename from docs/interop/qemu-img.rst
> > rename to docs/tools/qemu-img.rst
> > diff --git a/docs/interop/qemu-nbd.rst b/docs/tools/qemu-nbd.rst
> > similarity index 100%
> > rename from docs/interop/qemu-nbd.rst
> > rename to docs/tools/qemu-nbd.rst
> > 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
> > --
> > 2.20.1
> >
> --
> Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK
>
>

[-- Attachment #2: Type: text/html, Size: 14157 bytes --]

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH 3/3] docs: Move tools documentation to tools manual
  2020-02-17 18:41     ` Paolo Bonzini
@ 2020-02-17 19:19       ` Peter Maydell
  0 siblings, 0 replies; 11+ messages in thread
From: Peter Maydell @ 2020-02-17 19:19 UTC (permalink / raw)
  To: Paolo Bonzini
  Cc: Daniel P. Berrange, Dr. David Alan Gilbert, Stefan Hajnoczi,
	qemu-devel

On Mon, 17 Feb 2020 at 18:41, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
>
>
> Il lun 17 feb 2020, 19:24 Dr. David Alan Gilbert <dgilbert@redhat.com> ha scritto:
>>
>> * Peter Maydell (peter.maydell@linaro.org) wrote:
>> > Move the following tools documentation files to the new tools manual:
>> >
>> >  docs/interop/qemu-img.rst
>> >  docs/interop/qemu-nbd.rst
>> >  docs/interop/virtfs-proxy-helper.rst
>> >  docs/interop/qemu-trace-stap.rst
>> >  docs/interop/virtiofsd.rst
>> >
>> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>>
>> Would docs/tools be the right place for the virtiofsd security guide
>> (as previously posted there)?  It's not actually a manpage.
>
> Yes, I think it would.

I agree. (IMHO) tools/ is not "things with manpages" (we have
manpages like qemu-block-drivers.7 that live in system/), it's
"documentation relating to standalone tools". It's just
coincidence (plus the fact that often the only bit of documentation
a standalone tool has is its manpage) that all the things
that got moved in this patchset happen to generate manpages.

thanks
-- PMM


^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH 0/3] docs: Create a 'tools' manual
  2020-02-17 15:54 [PATCH 0/3] docs: Create a 'tools' manual Peter Maydell
                   ` (2 preceding siblings ...)
  2020-02-17 15:54 ` [PATCH 3/3] docs: Move tools documentation to tools manual Peter Maydell
@ 2020-02-17 16:00 ` Richard Henderson
  2020-02-17 16:04 ` Paolo Bonzini
  4 siblings, 0 replies; 11+ messages in thread
From: Richard Henderson @ 2020-02-17 16:00 UTC (permalink / raw)
  To: Peter Maydell, qemu-devel
  Cc: Paolo Bonzini, Daniel P. Berrange, Dr. David Alan Gilbert,
	Stefan Hajnoczi

On 2/17/20 7:54 AM, Peter Maydell wrote:
> Peter Maydell (3):
>   docs: Create new 'tools' manual
>   docs: Move qemu-option-trace.rst.inc to docs/
>   docs: Move tools documentation to tools manual

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~


^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH 0/3] docs: Create a 'tools' manual
  2020-02-17 15:54 [PATCH 0/3] docs: Create a 'tools' manual Peter Maydell
                   ` (3 preceding siblings ...)
  2020-02-17 16:00 ` [PATCH 0/3] docs: Create a 'tools' manual Richard Henderson
@ 2020-02-17 16:04 ` Paolo Bonzini
  2020-02-17 16:18   ` Peter Maydell
  4 siblings, 1 reply; 11+ messages in thread
From: Paolo Bonzini @ 2020-02-17 16:04 UTC (permalink / raw)
  To: Peter Maydell, qemu-devel
  Cc: Daniel P. Berrange, Dr. David Alan Gilbert, Stefan Hajnoczi

On 17/02/20 16:54, Peter Maydell wrote:
> This patchset creates the new 'tools' manual that we've
> decided we should have, and moves 5 existing documents to it:
> 
>  docs/interop/qemu-img.rst
>  docs/interop/qemu-nbd.rst
>  docs/interop/virtfs-proxy-helper.rst
>  docs/interop/qemu-trace-stap.rst
>  docs/interop/virtiofsd.rst
> 
> This change will conflict with the QAPI-doc-comment-to-rST
> patchset because they both change the docs/interop makefile
> rules, but I expect this one to get in to master first;
> the other needs a respin at some point anyhow.

Acked-by: Paolo Bonzini <pbonzini@redhat.com>

We can move them back to the system manual once it's converted to rST,
but for now it's the best solution.

(In fact, I am willing to do the conversion from texi to rST if: 1)
someone else helps with the .hx parts; 2) we accept that the current
structure of the manual isn't great but we agree to reorganize
everything after the conversion).

Paolo



^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH 0/3] docs: Create a 'tools' manual
  2020-02-17 16:04 ` Paolo Bonzini
@ 2020-02-17 16:18   ` Peter Maydell
  2020-02-17 16:29     ` Paolo Bonzini
  0 siblings, 1 reply; 11+ messages in thread
From: Peter Maydell @ 2020-02-17 16:18 UTC (permalink / raw)
  To: Paolo Bonzini
  Cc: Daniel P. Berrange, QEMU Developers, Stefan Hajnoczi,
	Dr. David Alan Gilbert

On Mon, 17 Feb 2020 at 16:04, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> On 17/02/20 16:54, Peter Maydell wrote:
> > This patchset creates the new 'tools' manual that we've
> > decided we should have, and moves 5 existing documents to it:
> >
> >  docs/interop/qemu-img.rst
> >  docs/interop/qemu-nbd.rst
> >  docs/interop/virtfs-proxy-helper.rst
> >  docs/interop/qemu-trace-stap.rst
> >  docs/interop/virtiofsd.rst
> >
> > This change will conflict with the QAPI-doc-comment-to-rST
> > patchset because they both change the docs/interop makefile
> > rules, but I expect this one to get in to master first;
> > the other needs a respin at some point anyhow.
>
> Acked-by: Paolo Bonzini <pbonzini@redhat.com>
>
> We can move them back to the system manual once it's converted to rST,
> but for now it's the best solution.

I think they can reasonably continue to live in tools/
even once we've got more stuff in system/.

> (In fact, I am willing to do the conversion from texi to rST if: 1)
> someone else helps with the .hx parts; 2) we accept that the current
> structure of the manual isn't great but we agree to reorganize
> everything after the conversion).

Yes, I'm definitely working on a "we can reshuffle stuff
later, but let's get the basic conversion done first" basis.

The mechanics for handling .hx files are already in the tree;
I can either help or work on the bit of qemu.1 that uses those.

Kashyap has volunteered to do qemu-cpu-models.texi.
I have patches on-list that try to do the QAPI doc-comments.

I think the next thing after this is to take chunks of documentation
that are currently used in qemu-doc.html but not put into the
qemu.1 manpage (ie which aren't in the 'man begin'/'man end'
sections), and convert those into individual .rst files
to go into docs/system:

 * docs/security.texi
 * qemu-tech.texi
 * qemu-deprecated.texi
 * various bits of qemu-doc.texi that don't go in the
   manpage and that are coherent chunks of documentation,
   eg "Supported build platforms", the various "$ARCH System emulator"
   sections

That will whittle qemu-doc.texi down to more or less just
the contents of the manpage. Then we can convert that
part to rST.

I note that softfreeze is now 1 month away -- we should
decide whether we think we can get this basically all
done by then, or whether there's a good "pause point"
we'd like to use where, say, most of qemu-doc.texi
remains as it is, or where it retains just the
content that goes into the qemu.1 manpage.

thanks
-- PMM


^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH 0/3] docs: Create a 'tools' manual
  2020-02-17 16:18   ` Peter Maydell
@ 2020-02-17 16:29     ` Paolo Bonzini
  0 siblings, 0 replies; 11+ messages in thread
From: Paolo Bonzini @ 2020-02-17 16:29 UTC (permalink / raw)
  To: Peter Maydell
  Cc: Daniel P. Berrange, QEMU Developers, Stefan Hajnoczi,
	Dr. David Alan Gilbert

On 17/02/20 17:18, Peter Maydell wrote:
> The mechanics for handling .hx files are already in the tree;
> I can either help or work on the bit of qemu.1 that uses those.

Right, basically if somebody else does qemu.1 I won't complain. :)  But
recently I retested the makeinfo+pandoc magic formulae that convert the
rest into rST and they work so I can take care of that part.

> Kashyap has volunteered to do qemu-cpu-models.texi.
> I have patches on-list that try to do the QAPI doc-comments.
> 
> I think the next thing after this is to take chunks of documentation
> that are currently used in qemu-doc.html but not put into the
> qemu.1 manpage (ie which aren't in the 'man begin'/'man end'
> sections), and convert those into individual .rst files
> to go into docs/system:
> 
>  * docs/security.texi
>  * qemu-tech.texi
>  * qemu-deprecated.texi
>  * various bits of qemu-doc.texi that don't go in the
>    manpage and that are coherent chunks of documentation,
>    eg "Supported build platforms", the various "$ARCH System emulator"
>    sections

One initial step here is to split qemu-doc.texi into separate Texinfo
files.  I can take a look at that as well.

Paolo

> That will whittle qemu-doc.texi down to more or less just
> the contents of the manpage. Then we can convert that
> part to rST.
> 
> I note that softfreeze is now 1 month away -- we should
> decide whether we think we can get this basically all
> done by then, or whether there's a good "pause point"
> we'd like to use where, say, most of qemu-doc.texi
> remains as it is, or where it retains just the
> content that goes into the qemu.1 manpage.



^ permalink raw reply	[flat|nested] 11+ messages in thread

end of thread, other threads:[~2020-02-17 19:21 UTC | newest]

Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-02-17 15:54 [PATCH 0/3] docs: Create a 'tools' manual Peter Maydell
2020-02-17 15:54 ` [PATCH 1/3] docs: Create new " Peter Maydell
2020-02-17 15:54 ` [PATCH 2/3] docs: Move qemu-option-trace.rst.inc to docs/ Peter Maydell
2020-02-17 15:54 ` [PATCH 3/3] docs: Move tools documentation to tools manual Peter Maydell
2020-02-17 18:24   ` Dr. David Alan Gilbert
2020-02-17 18:41     ` Paolo Bonzini
2020-02-17 19:19       ` Peter Maydell
2020-02-17 16:00 ` [PATCH 0/3] docs: Create a 'tools' manual Richard Henderson
2020-02-17 16:04 ` Paolo Bonzini
2020-02-17 16:18   ` Peter Maydell
2020-02-17 16:29     ` Paolo Bonzini

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).