Build docs/ in a single sphinx invocation instead of treating
docs/{devel,interop,specs} separately. This allows us to build a global
index page that links to documentation across the different manuals.
Some documentation is built outside of sphinx and is not formatted as
reStructuredText. Link directly to the .html files for the time being.
If they are converted to .rst files in the future they can be included
more elegantly.
Sphinx wants to build all .rst files and complains if they are not
listed in the table of contents. We have not yet reviewed and
categorized some of our .rst files. Hide these files so they are always
built (and syntax-checked from now on!) but not visible in the table of
contents.
Signed-off-by: Stefan Hajnoczi <stefa...@redhat.com>
---
Makefile | 13 ++++---------
docs/index.rst | 27 ++++++++++++++++++++++++++-
2 files changed, 30 insertions(+), 10 deletions(-)
diff --git a/Makefile b/Makefile
index aa9d1a42aa..9487a06bed 100644
--- a/Makefile
+++ b/Makefile
@@ -815,6 +815,7 @@ endef
install-sphinxdocs: sphinxdocs
$(call install-manual,interop)
$(call install-manual,specs)
+ $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/index.html"
"$(DESTDIR)$(qemu_docdir)/index.html"
install-doc: $(DOCS) install-sphinxdocs
$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
@@ -1001,7 +1002,7 @@ 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)/index.html
# Canned command to build a single manual
# Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')
@@ -1012,14 +1013,8 @@ build-manual = $(call
quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if
# 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,html)
-
-$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
- $(call build-manual,interop,html)
-
-$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
- $(call build-manual,specs,html)
+$(MANUAL_BUILDDIR)/index.html: $(call manual-deps,)
+ $(call build-manual,,html)
$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)
$(call build-manual,interop,man)
diff --git a/docs/index.rst b/docs/index.rst
index baa5791c17..9d6d239561 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,11 +6,36 @@
Welcome to QEMU's documentation!
================================
+.. Non-rst documentation
+
+`QEMU User Documentation <qemu-doc.html>`_
+
+`QEMU QMP Reference Manual <qemu-doc.html>`_
+
+`QEMU Guest Agent Protocol Reference <qemu-doc.html>`_
+
.. toctree::
:maxdepth: 2
:caption: Contents:
interop/index
- devel/index
specs/index
+.. The QEMU Developer's Guide is not included in the main documentation because
+ users don't need it.
+.. toctree::
+ :hidden:
+
+ devel/index
+
+.. Hidden documents that still need to be reviewed and moved to the appropriate
+ section of the documentation.
+.. toctree::
+ :hidden:
+
+ arm-cpu-features
+ cpu-hotplug
+ microvm
+ pr-manager
+ virtio-net-failover
+ virtio-pmem
--
2.23.0
