Sphinx and the :any: role

[John Snow <jsnow@redhat.com>]

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