[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 2/5] docs/sphinx: Add new hxtool Sphinx extension
From: |
Richard Henderson |
Subject: |
Re: [PATCH 2/5] docs/sphinx: Add new hxtool Sphinx extension |
Date: |
Tue, 21 Jan 2020 11:53:58 -1000 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 |
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~
- [PATCH 0/5] qemu-img: convert to rST, Peter Maydell, 2020/01/21
- [PATCH 3/5] qemu-img-cmds.hx: Add rST documentation fragments, 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