On 1/21/20 9:10 AM, Peter Maydell wrote: > 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.mayd...@linaro.org>
This doesn't seem to work for me. make[1]: Leaving directory '/home/rth/qemu/qemu/slirp' CONFDIR="/home/rth/qemu/run/etc/qemu" sphinx-build -W -b html -D version=4.2.50 -D release="4.2.50 (rth)" -d .doctrees/devel-html /home/rth/qemu/qemu/docs/devel docs/devel Running Sphinx v1.8.5 Extension error: Could not import extension hxtool (exception: cannot import name ExtensionError) make: *** [Makefile:1022: docs/devel/index.html] Error 2 > @@ -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, '..') I wondered if there was something more needed here? > diff --git a/docs/sphinx/hxtool.py b/docs/sphinx/hxtool.py The actual code looks fine. r~
