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
This commit is contained in:
parent
bccb135e54
commit
de1572ca49
1
Makefile
1
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")
|
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
|
# We assume all RST files in the manual's directory are used in it
|
||||||
manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \
|
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
|
$(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
|
||||||
# Macro to write out the rule and dependencies for building manpages
|
# Macro to write out the rule and dependencies for building manpages
|
||||||
# Usage: $(call define-manpage-rule,manualname,manpage1 manpage2...[,extradeps])
|
# Usage: $(call define-manpage-rule,manualname,manpage1 manpage2...[,extradeps])
|
||||||
|
|
|
@ -132,6 +132,12 @@ suppress_warnings = ["ref.option"]
|
||||||
# style document building; our Makefile always sets the variable.
|
# style document building; our Makefile always sets the variable.
|
||||||
confdir = os.getenv('CONFDIR', "/etc/qemu")
|
confdir = os.getenv('CONFDIR', "/etc/qemu")
|
||||||
rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
|
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 ----------------------------------------------
|
# -- Options for HTML output ----------------------------------------------
|
||||||
|
|
||||||
|
|
11
docs/defs.rst.inc
Normal file
11
docs/defs.rst.inc
Normal file
|
@ -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
|
|
@ -3,8 +3,6 @@
|
||||||
QEMU block drivers reference
|
QEMU block drivers reference
|
||||||
============================
|
============================
|
||||||
|
|
||||||
.. |qemu_system| replace:: qemu-system-x86_64
|
|
||||||
|
|
||||||
Synopsis
|
Synopsis
|
||||||
--------
|
--------
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue