[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v3 14/33] docs: Create defs.rst.inc as a place to define subs
From: |
Kashyap Chamarthy |
Subject: |
Re: [PATCH v3 14/33] docs: Create defs.rst.inc as a place to define substitutions |
Date: |
Mon, 2 Mar 2020 13:40:44 +0100 |
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 <address@hidden>
Reviewed-by: Kashyap Chamarthy <address@hidden>
> ---
> 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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Re: [PATCH v3 14/33] docs: Create defs.rst.inc as a place to define substitutions,
Kashyap Chamarthy <=