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.

Add a comment noting a pitfall where putting literal markup in the
definition of |qemu_system| makes it misrender manpage output; this
means the point-of-use must handle the literal markup (which is
almost always done by having it inside a parsed-literal block).

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Message-id: 20200228153619.9906-15-peter.maydell@linaro.org

1 files changed, 6 insertions, 0 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 7588bf1..960043c 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 ----------------------------------------------