diff options
authorPeter Maydell <peter.maydell@linaro.org>2020-02-27 13:41:02 +0000
committerPeter Maydell <peter.maydell@linaro.org>2020-02-27 13:41:02 +0000
commitaee42e6ae87f4ef81219a4042888c625e374364c (patch)
parent836bbc7f0bc54d5981a91e39131f6fb5ff8d6ebc (diff)
docs: Create defs.rst.inc as a place to define substitutions
Rather than accumulating generally useful rST substitution definitions in individual rST files, create a defs.rst.inc where we can define these. To start with it has the |qemu_system| definition from qemu-block-drivers.rst. Since we're making |qemu_system| generally available, add the ``...`` literal markup so it can be used in running text as well as inside a parsed-literal block. Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
4 files changed, 13 insertions, 2 deletions
diff --git a/Makefile b/Makefile
index 7e60a43542..26bbd33443 100644
--- a/Makefile
+++ b/Makefile
@@ -1052,6 +1052,7 @@ 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) \
+ $(SRC_PATH)/docs/defs.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])
diff --git a/docs/conf.py b/docs/conf.py
index 7588bf192e..960043cb86 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -132,6 +132,12 @@ suppress_warnings = ["ref.option"]
# style document building; our Makefile always sets the variable.
confdir = os.getenv('CONFDIR', "/etc/qemu")
rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
+# We slurp in the defs.rst.inc and literally include it into rst_epilog,
+# because Sphinx's include:: directive doesn't work with absolute paths
+# and there isn't any one single relative path that will work for all
+# documents and for both via-make and direct sphinx-build invocation.
+with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f:
+ rst_epilog += f.read()
# -- Options for HTML output ----------------------------------------------
diff --git a/docs/defs.rst.inc b/docs/defs.rst.inc
new file mode 100644
index 0000000000..860112c5e4
--- /dev/null
+++ b/docs/defs.rst.inc
@@ -0,0 +1,6 @@
+ Generally useful rST substitution definitions. This is included for
+ all rST files as part of the epilogue by docs/conf.py. conf.py
+ also defines some dynamically generated substitutions like CONFDIR.
+.. |qemu_system| replace:: ``qemu-system-x86_64``
diff --git a/docs/system/qemu-block-drivers.rst b/docs/system/qemu-block-drivers.rst
index 7ca890ea23..bd99d4fa8e 100644
--- a/docs/system/qemu-block-drivers.rst
+++ b/docs/system/qemu-block-drivers.rst
@@ -3,8 +3,6 @@
QEMU block drivers reference
-.. |qemu_system| replace:: qemu-system-x86_64