OpenE2K
/
qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

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:
Peter Maydell 2020-02-28 15:36:00 +00:00
parent bccb135e54
commit de1572ca49
4 changed files with 18 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Makefile
View File

@ -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])

6
docs/conf.py
View File

@ -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 ----------------------------------------------

11
docs/defs.rst.inc Normal file
View 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

2
docs/system/qemu-block-drivers.rst
View File

@ -3,8 +3,6 @@
QEMU block drivers reference
============================
.. |qemu_system| replace:: qemu-system-x86_64
Synopsis
--------