Where do these "<unknown>" Sphinx messages come from?

Documentation
1

Looking at the output of running sphinx-build in nitpicky mode, I see lots of warnings where the filename shows as <unknown>. Here are a few:

<unknown>:211: WARNING: c:data reference target not found: PyExc_EncodingWarning
<unknown>:212: WARNING: c:data reference target not found: PyExc_EnvironmentError
<unknown>:219: WARNING: c:data reference target not found: PyExc_IOError
<unknown>:222: WARNING: c:data reference target not found: PyExc_IncompleteInputError

Consider the third message about PyExc_IOError. I find it mentioned twice in the rst files:

% find . -name '*.rst' -print0 | xargs -0 egrep -n 'PyExc_IOError'
./c-api/exceptions.rst:1155:   single: PyExc_IOError
./c-api/exceptions.rst:1163:| :c:data:`PyExc_IOError`             |          |

Note that neither occurrence is on line 219.

Where is Sphinx finding these?

2

Must they com from .rst files?

It looks like there’s a close match for PyExc_IOError in cpython/Doc/data/stable_abi.dat.

3

Most likely the .. limited-api-list:: directive in Doc/c-api/stable.rst, implemented in Doc/tools/extensions/c_annotations.py.

A

2 Likes
4

I sorta thought Sphinx took .rst files as input. Are .dat files consumed as well?

5

Hmmm… Why wouldn’t Sphinx know the name of that file for producing warnings?

6

Custom extensions can read and do anything they like.

7

data/stable_api.dat is a bespoke data file consumed by the custom limited-api-list directive to produce the limited API list, and IIRC to also automatically annotate APIs that are part of the stable ABI.

Presumably the custom limited-api-list directive does not set node.source on the affected doctree node (while node.line is set), either unintentionally or because technically speaking, there is no one specific source file for the content, it is generated by the directive.

8

After further searching, it looks like stable_abi.dat is a generated file.

9

This does come from an extension: specifically, the limited API list generated from – you guessed it – stable_abi.dat.

I commented on the issue that added PyExc_IncompleteInputError: #113744
The others look pre-existing. They should be added to Exception Handling — Python 3.12.1 documentation – usually as a link to the Python exception, which in turn needs docs as well (unless the C name is a backwards-conmatibility alias to a documented exception).

Ideally, the extensions would emit something useful instead of <unknown>. This particular extension is at c_annotations.py:199; other extensions might want similar fixes.