[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 2/5] docs/sphinx: Add new hxtool Sphinx extension
From: |
Peter Maydell |
Subject: |
Re: [PATCH 2/5] docs/sphinx: Add new hxtool Sphinx extension |
Date: |
Tue, 21 Jan 2020 22:22:22 +0000 |
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
- [PATCH 0/5] qemu-img: convert to rST, Peter Maydell, 2020/01/21
- [PATCH 5/5] qemu-img-cmds.hx: Remove texinfo document fragments, Peter Maydell, 2020/01/21
- [PATCH 4/5] qemu-img: Convert invocation documentation to rST, Peter Maydell, 2020/01/21
- Re: [PATCH 0/5] qemu-img: convert to rST, no-reply, 2020/01/21
- Re: [PATCH 0/5] qemu-img: convert to rST, no-reply, 2020/01/21