aboutsummaryrefslogtreecommitdiff
path: root/docs/conf.py
diff options
context:
space:
mode:
authorPeter Maydell <peter.maydell@linaro.org>2020-01-24 16:26:01 +0000
committerPeter Maydell <peter.maydell@linaro.org>2020-02-03 10:46:32 +0000
commit6803d6e9a7d951cd65bbdd88bfe6f8a921c95f54 (patch)
tree0740ed57be6408d22c2f4c43070c639bdd7b72da /docs/conf.py
parentb0cecc0d65ec7c4c06cfd987e79eab1a0afee39b (diff)
docs/sphinx: Add new hxtool Sphinx extension
Some of our documentation includes sections which are created by assembling fragments of texinfo from a .hx source file into a .texi file, which is then included from qemu-doc.texi or qemu-img.texi. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which reads the .hx file and process it. So instead of: * makefile produces foo.texi from foo.hx * qemu-doc.texi says '@include foo.texi' we have: * qemu-doc.rst says 'hxtool-doc:: foo.hx' * the Sphinx extension for hxtool has code that runs to handle that Sphinx directive which reads the .hx file and emits the appropriate documentation contents This is pretty much the same way the kerneldoc extension works right now. It also has the advantage that it should work for third-party services like readthedocs that expect to build the docs directly with sphinx rather than by invoking our makefiles. In this commit we implement the hxtool extension. Note that syntax errors in the rST fragments will be correctly reported to the user with the filename and line number within the hx file. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Message-id: 20200124162606.8787-4-peter.maydell@linaro.org
Diffstat (limited to 'docs/conf.py')
-rw-r--r--docs/conf.py3
1 files changed, 2 insertions, 1 deletions
diff --git a/docs/conf.py b/docs/conf.py
index 259c6049da..ee7faa6b4e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -54,7 +54,7 @@ needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['kerneldoc', 'qmp_lexer']
+extensions = ['kerneldoc', 'qmp_lexer', 'hxtool']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -221,3 +221,4 @@ texinfo_documents = [
# find everything.
kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc')
kerneldoc_srctree = os.path.join(qemu_docdir, '..')
+hxtool_srctree = os.path.join(qemu_docdir, '..')