Re: [PATCH 2/5] docs/sphinx: Add new hxtool Sphinx extension

[Peter Maydell]

On Tue, 21 Jan 2020 at 21:54, Richard Henderson
<address@hidden> 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 <address@hidden>
>
> 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