From de1572ca4902c057b100d5c3434f254dfc677ddd Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Fri, 28 Feb 2020 15:36:00 +0000 Subject: [PATCH] docs: Create defs.rst.inc as a place to define substitutions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Kashyap Chamarthy Tested-by: Alex Bennée Message-id: 20200228153619.9906-15-peter.maydell@linaro.org --- Makefile | 1 + docs/conf.py | 6 ++++++ docs/defs.rst.inc | 11 +++++++++++ docs/system/qemu-block-drivers.rst | 2 -- 4 files changed, 18 insertions(+), 2 deletions(-) create mode 100644 docs/defs.rst.inc 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..ae80d2f35d --- /dev/null +++ b/docs/defs.rst.inc @@ -0,0 +1,11 @@ +.. + 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. + + Note that |qemu_system| is intended to be used inside a parsed-literal + block: the definition must not include extra literal formatting with + ``..``: this works in the HTML output but the manpages will end up + misrendered with following normal text incorrectly in boldface. + +.. |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 - Synopsis --------