On Tue, 21 Jan 2020 at 21:54, Richard Henderson <richard.hender...@linaro.org> wrote: > > 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
I suspect this is an incompatibility (or possibly just a dropped back-compatibility I was accidentally relying on) between Sphinx 1.7 and 1.8. (I tested with a 1.6 and a 1.7.) It looks like ExtensionError is now in sphinx.errors, so if you change +from sphinx.application import ExtensionError to "from sphinx.errors import ExtensionError" does that help? If so then I'll test later this week whether that works also for 1.7/1.6 or if we need to do some version-specific stuff. thanks -- PMM
