From: Richard Henderson <richard.henderson@linaro.org>
To: Peter Maydell <peter.maydell@linaro.org>, qemu-devel@nongnu.org
Cc: Kevin Wolf <kwolf@redhat.com>,
qemu-block@nongnu.org, Markus Armbruster <armbru@redhat.com>,
Max Reitz <mreitz@redhat.com>,
Stefan Hajnoczi <stefanha@redhat.com>,
John Snow <jsnow@redhat.com>
Subject: Re: [PATCH 2/5] docs/sphinx: Add new hxtool Sphinx extension
Date: Tue, 21 Jan 2020 11:53:58 -1000 [thread overview]
Message-ID: <5fa9a519-d9c8-13b6-2d38-efa12c29780d@linaro.org> (raw)
In-Reply-To: <20200121191033.28195-3-peter.maydell@linaro.org>
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.maydell@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
> @@ -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~
next prev parent reply other threads:[~2020-01-21 21:55 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-01-21 19:10 [PATCH 0/5] qemu-img: convert to rST Peter Maydell
2020-01-21 19:10 ` [PATCH 1/5] hxtool: Support SRST/ERST directives Peter Maydell
2020-01-21 20:33 ` Richard Henderson
2020-01-21 19:10 ` [PATCH 2/5] docs/sphinx: Add new hxtool Sphinx extension Peter Maydell
2020-01-21 21:53 ` Richard Henderson [this message]
2020-01-21 22:22 ` Peter Maydell
2020-01-22 0:15 ` Richard Henderson
2020-01-23 17:33 ` Peter Maydell
2020-01-21 19:10 ` [PATCH 3/5] qemu-img-cmds.hx: Add rST documentation fragments Peter Maydell
2020-01-21 21:55 ` Richard Henderson
2020-01-21 19:10 ` [PATCH 4/5] qemu-img: Convert invocation documentation to rST Peter Maydell
2020-01-21 19:10 ` [PATCH 5/5] qemu-img-cmds.hx: Remove texinfo document fragments Peter Maydell
2020-01-21 21:55 ` Richard Henderson
2020-01-21 20:16 ` [PATCH 0/5] qemu-img: convert to rST no-reply
2020-01-21 20:55 ` no-reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5fa9a519-d9c8-13b6-2d38-efa12c29780d@linaro.org \
--to=richard.henderson@linaro.org \
--cc=armbru@redhat.com \
--cc=jsnow@redhat.com \
--cc=kwolf@redhat.com \
--cc=mreitz@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-block@nongnu.org \
--cc=qemu-devel@nongnu.org \
--cc=stefanha@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).