From: John Snow <jsnow@redhat.com>
To: QEMU Developers <qemu-devel@nongnu.org>,
Peter Maydell <peter.maydell@linaro.org>
Cc: Paolo Bonzini <pbonzini@redhat.com>,
Markus Armbruster <armbru@redhat.com>
Subject: Sphinx and the :any: role
Date: Tue, 11 May 2021 13:31:59 -0400 [thread overview]
Message-ID: <9fe98807-7d68-2c86-163a-af374c789401@redhat.com> (raw)
For the purposes of my QAPI generator cleanup (adding docstrings and
mypy static types to ./scripts/qapi), I have a series of patches I've
been carrying off-list that changes the behavior of how Sphinx
cross-references work.
Presently, `foo` in our Sphinx docs is interpreted as the "content"
role, and has "no special meaning".
I experimented with what would happen if we change this to the "any"
role, which interprets `foo` as a cross-reference to *something* named
"foo". If no reference is found, it emits a build error.
(Many existing usages of `foo` must be changed to ``foo`` to enable this
to work.)
I found this useful for testing and writing Python docstrings, because
it keeps the syntax cleaner than having to write :py:func:`foo` or
:py:meth:`foo` and so on. It keeps the docstrings less syntax-heavy when
reading them outside of the Sphinx rendered output.
I would have liked to propose we actually adopt this change, however
I've noticed a problem with this in our CI builds.
Sphinx 3.2.1 (The current version we seem to test against in our Fedora
container) has a race condition (?) where occasionally kernel-doc will
crash outright:
Exception occurred:
File "/usr/lib/python3.9/site-packages/sphinx/domains/c.py", line
3751, in resolve_any_xref
return [('c:' + self.role_for_objtype(objtype), retnode)]
TypeError: can only concatenate str (not "NoneType") to str
The full traceback has been saved in /tmp/sphinx-err-v6iqwtf9.log, if
you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error
message can be provided next time.
A bug report can be filed in the tracker at
<https://github.com/sphinx-doc/sphinx/issues>. Thanks!
It's not actually clear WHICH thing Sphinx is choking on here, exactly
-- it's just some bug in Sphinx's C domain handling of resolving
cross-references.
This is fixed in 3.3.1, I believe closed with one of these issues:
https://github.com/sphinx-doc/sphinx/issues/8364
https://github.com/sphinx-doc/sphinx/issues/8388
I'm not sure if there's anything I can do here -- we probably can't
require such a modern version of Sphinx just yet, I haven't done the
legwork to check. I also haven't been able to diagnose the exact
invocation that seems to trigger these failures, so it's not clear if
there's a workaround just yet.
I'm still interested in making our cross-referencing a bit more robust,
but maybe my hands are tied on that front for now.
--js
next reply other threads:[~2021-05-11 17:33 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-11 17:31 John Snow [this message]
2021-05-11 22:34 ` Sphinx and the :any: role John Snow
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=9fe98807-7d68-2c86-163a-af374c789401@redhat.com \
--to=jsnow@redhat.com \
--cc=armbru@redhat.com \
--cc=pbonzini@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.