[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v3 14/33] docs: Create defs.rst.inc as a place to define substitu
From: |
Peter Maydell |
Subject: |
[PATCH v3 14/33] docs: Create defs.rst.inc as a place to define substitutions |
Date: |
Fri, 28 Feb 2020 15:36:00 +0000 |
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>
---
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:
+ 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.
+
+.. |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
- [PATCH v3 02/33] qemu-doc: remove target OS documentation, (continued)
- [PATCH v3 02/33] qemu-doc: remove target OS documentation, Peter Maydell, 2020/02/28
- [PATCH v3 03/33] texi2pod: parse @include directives outside "@c man" blocks, Peter Maydell, 2020/02/28
- [PATCH v3 01/33] qemu-doc: convert user-mode emulation to a separate Sphinx manual, Peter Maydell, 2020/02/28
- [PATCH v3 06/33] qemu-doc: extract common system emulator documentation from the PC section, Peter Maydell, 2020/02/28
- [PATCH v3 07/33] qemu-doc: move system requirements chapter inside PC section, Peter Maydell, 2020/02/28
- [PATCH v3 04/33] qemu-doc: split CPU models doc between MIPS and x86 parts, Peter Maydell, 2020/02/28
- [PATCH v3 15/33] docs/system: Convert qemu-cpu-models.texi to rST, Peter Maydell, 2020/02/28
- [PATCH v3 10/33] qemu-doc: move qemu-tech.texi into main section, Peter Maydell, 2020/02/28
- [PATCH v3 11/33] qemu-doc: move included files to docs/system, Peter Maydell, 2020/02/28
- [PATCH v3 12/33] qemu-doc: remove indices other than findex, Peter Maydell, 2020/02/28
- [PATCH v3 14/33] docs: Create defs.rst.inc as a place to define substitutions,
Peter Maydell <=
- [PATCH v3 17/33] docs/system: convert managed startup to rST., Peter Maydell, 2020/02/28
- [PATCH v3 18/33] docs/system: convert the documentation of deprecated features to rST., Peter Maydell, 2020/02/28
- [PATCH v3 08/33] qemu-doc: split target sections to separate files, Peter Maydell, 2020/02/28
- [PATCH v3 09/33] qemu-doc: Remove the "CPU emulation" part of the "Implementation notes", Peter Maydell, 2020/02/28
- [PATCH v3 16/33] docs/system: Convert security.texi to rST format, Peter Maydell, 2020/02/28
- [PATCH v3 05/33] qemu-doc: split qemu-doc.texi in multiple files, Peter Maydell, 2020/02/28
- [PATCH v3 22/33] doc/scripts/hxtool.py: Strip trailing ':' from DEFHEADING/ARCHHEADING, Peter Maydell, 2020/02/28
- [PATCH v3 21/33] hmp-commands-info.hx: Add rST documentation fragments, Peter Maydell, 2020/02/28
- [PATCH v3 24/33] docs: Roll -prom-env and -g target-specific info into qemu-options.hx, Peter Maydell, 2020/02/28
- [PATCH v3 13/33] docs/system: put qemu-block-drivers body in an included file, Peter Maydell, 2020/02/28