[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Sphinx and the :any: role
From: |
John Snow |
Subject: |
Sphinx and the :any: role |
Date: |
Tue, 11 May 2021 13:31:59 -0400 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.8.1 |
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
- Sphinx and the :any: role,
John Snow <=