source-read for included files is called with a file path, not a docname

[lmoureaux]

Describe the bug

Since #10678, the source-read event is emitted for included files. The first argument passed to the function in this case is a file path, not a docname. This breaks hooks trying to access the document, except when building from the source folder. Extensions such as sphinx-last-updated-by-git (also currently broken for a different reason) would need to work around the present behavior.

How to Reproduce

Put the following in a folder called docs:

docs/conf.py:

import sys
import os

sys.path.insert(0, os.path.abspath('.'))

extensions = [
        'my-extension'
]

docs/index.rst:

This is a test
==============

.. include:: something-to-include.rst

docs/something-to-include.rst:

Testing
=======

docs/my-extension.py:

#!/usr/bin/env python3

import os

from sphinx.application import Sphinx


__version__ = '1.0'


def check_doc_file(app: Sphinx, docname, source):
    path = app.env.doc2path(docname, True)
    print(docname, path)
    assert os.path.isfile(path)


def setup(app: Sphinx):

    app.connect('source-read', check_doc_file)

    return dict(
        version=__version__,
        parallel_read_safe=True,
        parallel_write_safe=True
    )

Then execute:

sphinx-build docs build # fails
cd docs; sphinx-build . ../build # works

Environment Information

Platform:              linux; (Linux-6.2.0-26-generic-x86_64-with-glibc2.35)
Python version:        3.10.12 (main, Jun 11 2023, 05:26:28) [GCC 11.4.0])
Python implementation: CPython
Sphinx version:        7.2.3
Docutils version:      0.20.1
Jinja2 version:        3.1.2
Pygments version:      2.16.1

Sphinx extensions

See minimal example above.

Additional context

Debugging longturn/freeciv21#2023

[AA-Turner]

I think this has been fixed by #11650 (the example in the body of the issue no longer fails)

A

[lmoureaux]

Confirmed fixed, thanks!

[mgeier]

This is still a bit fishy.

If you use a path outside the source directory, e.g.

.. include:: ../../some/path/included-file.rst

... AND if the first element of source_suffix doesn't match the suffix, e.g.

source_suffix = ['.nonsense', '.rst']

... then it breaks, because the first source_suffix is appended.

[AA-Turner]

Now resolved by #11657 as we no longer try and convert the path to a docname.