From 6803d6e9a7d951cd65bbdd88bfe6f8a921c95f54 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Fri, 24 Jan 2020 16:26:01 +0000 Subject: docs/sphinx: Add new hxtool Sphinx extension MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Alex Bennée Tested-by: Alex Bennée Message-id: 20200124162606.8787-4-peter.maydell@linaro.org --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/conf.py') 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, '..') -- cgit v1.2.3