Warning for include directive shows wrong path

[arwedus]

Describe the bug

If the author provides an absolute path to the include directive, and the file does not exist, the warning message prepends the relative path of the document containing the include directive, which leads to confusing output.

E.g., a file "source/index.rst" in a folder named /home/user/projects/sphinx-include-example contains:

.. include:: /home/user/projects/sphinx-include-example/build/generated_images.rst

The file does not exist. The warning message is:

/home/user/projects/sphinx-include-example/source/index.rst:16: CRITICAL: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/home/user/projects/sphinx-include-example/build/generated_images.rst'.

How to Reproduce

• Create a minimal example with sphinx-quickstart, with separate build paths
• Add the above include directive to index.rst
• run make html

Environment Information

Platform:              linux; (Linux-5.15.0-88-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:        5.3.0
Docutils version:      0.17.1
Jinja2 version:        3.0.3

Sphinx extensions

none

Additional context

Tested also with sphinx 6.1.3, the issue is the same:

```text
Platform:              linux; (Linux-5.15.0-88-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:        6.1.3
Docutils version:      0.18.1
Jinja2 version:        3.0.3
Pygments version:      2.16.1

[arwedus]

Actually, the whole feature seems to be at least not clearly documented.

Including files from outside the sphinx source tree (used e.g. to keep the source tree clean when including generated .rst files) does not work like this:

.. include:: /home/user/projects/sphinx-include-example/build/generated_images.rst

-> of course! I remembered, the single leading slash refers to the source root directory in sphinx!

Instead, you have to add two leading slashes:

.. include:: //home/user/projects/sphinx-include-example/build/generated_images.rst

-> Now, the argument is interpreted as an absolute path, as was my intention.

Seems related to this issue: #7772

[picnixz]

Yeah I more or less agree that there are still a lot of confusion with how paths are treated inside a directive.

For instance, 'document' does not always refer to the your 'real' document (like your document on your filesystem with the '.. include' text). So we need to make it clear in our docs (and it's not only for the 'include' directive, it's mostly for all path-related directives).

So technically, it works as intended (although the // hack is not recommended). We must probably add a directive option where you can interpret the file to include as being "absolute". It leads to security holes so it should be used only in a trusted environment (and usually only "locally" on your own machine).

For instance, you can't expect the project to build on other's machines if you add absolute paths like that. Or we could alternatively have something like 'relative to this specific file that triggered the directive' (and you could somewhat still be in the sphinx environment).

Anyway, we need a PR fixing all docs at the same time (otherwise, we'll just face the same problems every time) and another PR for handling this hacky //.