On Fri, Feb 28, 2020 at 03:36:00PM +0000, Peter Maydell wrote: > 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.mayd...@linaro.org>
Reviewed-by: Kashyap Chamarthy <kcham...@redhat.com> > --- > 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 7e60a435426..26bbd334438 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 7588bf192ee..960043cb860 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: I didn't know about the above quirk; thanks for the explanatory comment. > + 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 00000000000..ae80d2f35d8 > --- /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. Thanks for documenting the above bit here. (I learnt about it from you on IRC.) > +.. |qemu_system| replace:: qemu-system-x86_64 > diff --git a/docs/system/qemu-block-drivers.rst > b/docs/system/qemu-block-drivers.rst > index 7ca890ea23a..bd99d4fa8eb 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 > -------- > > -- > 2.20.1 > -- /kashyap