Documentation of source-read event: "docname" can be None

[mgeier]

Describe the bug

When including a file with the include directive, the docname argument can be None (since Sphinx 7.2).

The docs don't mention that: https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-source-read

How to Reproduce

conf.py:

def source_read(app, docname, source):
    print('#####')
    print('docname:', docname)


def setup(app):
    app.connect('source-read', source_read)

index.rst:

.. include:: another-file.txt

another-file.txt:

Some text.

Run this:

python -m sphinx . _build

... and check the terminal output.

Environment Information

Platform:              linux; (Linux-6.4.0-1-amd64-x86_64-with-glibc2.37)
Python version:        3.11.4 (main, Jun  7 2023, 10:13:09) [GCC 12.2.0])
Python implementation: CPython
Sphinx version:        7.2.0
Docutils version:      0.18.1
Jinja2 version:        3.1.2
Pygments version:      2.15.1

Sphinx extensions

none, but this behavior is relevant for extensions that want to use the source-read event, like in my case https://github.com/mgeier/sphinx-last-updated-by-git

Additional context

Maybe related: #11643

Possible work-around: mgeier/sphinx-last-updated-by-git#59

[picnixz]

Probably related to the issue you linked. Haven't looked at it in details, but for included files, what should be the docname then? btw the environment exposes some method to get a docname from a path iirc so it should be easily fixable.

[AA-Turner]

I investigated here, perhaps relevant:

#11510 fixed a previous failure to emit source-read for uses of the .. include:: directive. Such directives are emitted by the .. minigallery:: directive. BuildEnvironment.path2doc will then try and resolve a path similar to gen_modules/backreferences/sphinx_gallery.backreferences.identify_names.examples to a document name, which will fail as the document does not have a suffix contained within app.config.source_suffix.

A

[AA-Turner]

See #11657 for an update.