qemu-e2k/docs/sphinx
Peter Maydell 6803d6e9a7 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
2020-02-03 10:46:32 +00:00
..
hxtool.py docs/sphinx: Add new hxtool Sphinx extension 2020-02-03 10:46:32 +00:00
kerneldoc.py docs: import Linux kernel-doc script and extension 2019-12-17 19:36:32 +01:00
kernellog.py docs: import Linux kernel-doc script and extension 2019-12-17 19:36:32 +01:00
qmp_lexer.py sphinx: add qmp_lexer 2019-07-10 15:08:06 -04:00