From 0928523a1230a690c933cee6e353e06b0810c7c6 Mon Sep 17 00:00:00 2001
From: Peter Maydell <peter.maydell@linaro.org>
Date: Thu, 23 Jan 2020 15:22:40 +0000
Subject: [PATCH] docs: Create stub system manual
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We want a user-facing manual which contains system emulation
documentation. Create an empty one which we can populate.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-id: 20200116141511.16849-3-peter.maydell@linaro.org
---
 Makefile              | 10 +++++++++-
 docs/index.html.in    |  1 +
 docs/index.rst        |  2 +-
 docs/system/conf.py   | 15 +++++++++++++++
 docs/system/index.rst | 16 ++++++++++++++++
 5 files changed, 42 insertions(+), 2 deletions(-)
 create mode 100644 docs/system/conf.py
 create mode 100644 docs/system/index.rst

diff --git a/Makefile b/Makefile
index b4a6c28107..2ab6a17205 100644
--- a/Makefile
+++ b/Makefile
@@ -757,6 +757,7 @@ distclean: clean
 	$(call clean-manual,devel)
 	$(call clean-manual,interop)
 	$(call clean-manual,specs)
+	$(call clean-manual,system)
 	for d in $(TARGET_DIRS); do \
 	rm -rf $$d || exit 1 ; \
         done
@@ -813,6 +814,7 @@ endef
 install-sphinxdocs: sphinxdocs
 	$(call install-manual,interop)
 	$(call install-manual,specs)
+	$(call install-manual,system)
 
 install-doc: $(DOCS) install-sphinxdocs
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
@@ -1000,7 +1002,10 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak
 # and handles "don't rebuild things unless necessary" itself.
 # The '.doctrees' files are cached information to speed this up.
 .PHONY: sphinxdocs
-sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html $(MANUAL_BUILDDIR)/specs/index.html
+sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \
+            $(MANUAL_BUILDDIR)/interop/index.html \
+            $(MANUAL_BUILDDIR)/specs/index.html \
+            $(MANUAL_BUILDDIR)/system/index.html
 
 # Canned command to build a single manual
 # Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')
@@ -1022,6 +1027,9 @@ $(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
 $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
 	$(call build-manual,specs,html)
 
+$(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)
 
diff --git a/docs/index.html.in b/docs/index.html.in
index 94eb782cf7..8512933d14 100644
--- a/docs/index.html.in
+++ b/docs/index.html.in
@@ -12,6 +12,7 @@
             <li><a href="qemu-ga-ref.html">Guest Agent Protocol Reference</a></li>
             <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>
         </ul>
     </body>
 </html>
diff --git a/docs/index.rst b/docs/index.rst
index baa5791c17..46405d4f07 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,4 +13,4 @@ Welcome to QEMU's documentation!
    interop/index
    devel/index
    specs/index
-
+   system/index
diff --git a/docs/system/conf.py b/docs/system/conf.py
new file mode 100644
index 0000000000..6435b4d3f8
--- /dev/null
+++ b/docs/system/conf.py
@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+#
+# QEMU documentation build configuration file for the 'system' 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'System Emulation User''s Guide'
diff --git a/docs/system/index.rst b/docs/system/index.rst
new file mode 100644
index 0000000000..ea8ea5fe3d
--- /dev/null
+++ b/docs/system/index.rst
@@ -0,0 +1,16 @@
+.. This is the top level page for the 'system' manual.
+
+
+QEMU System Emulation User's Guide
+==================================
+
+This manual is the overall guide for users using QEMU
+for full system emulation (as opposed to user-mode emulation).
+This includes working with hypervisors such as KVM, Xen, Hax
+or Hypervisor.Framework.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+