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

[Richard Henderson]

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

> @@ -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~