include directive does not comply with specification

[dstadelm]

Describe the bug
The specification for the included directive from https://docutils.sourceforge.io/docs/ref/rst/directives.html states

The "include" directive reads a text file. The directive argument is the path to the file to be included, relative to the document containing the directive. Unless the options literal, code, or parser are given, the file is parsed in the current document's context at the point of the directive.

To Reproduce
Steps to reproduce the behavior:

Given following directory structure:

With file contents:

foo.rst
.. include:: bar/bar.rst

bar/bar.rst

.. include:: here.rst
.. include:: there/file.rst

bar/here.rst

I'm here
========

bar/there/file.rst

I'm there
=========

Expected behavior
docutils rst2html will correctly include file.rst whereas sphinx doesn't find the file as it will search for it in <root>/there/ instead of <root>/bar/there

Your project
Link to your sphinx project, or attach zipped small project sample.
demo.zip

Screenshots
Docutils output:

Sphinx output:

Environment info

• OS: Linux
• Python version: 3.8.5
• Sphinx version: sphinx-build v 4.0.1
• Sphinx extensions: -
• Extra tools: -

Additional context

[dstadelm]

May I ask if this isn't considered to be a bug. I would be happy to contribute if anybody would reply on the desired behaviour.

[AA-Turner]

We've been discussing this on the Docutils tracker as for multi-file projects it may be more desirable to have a 'include root' which specifies the root from which files are to be included from. Sphinx implicitly uses the project root as the 'include root', a side effect of the implementation details of Sphinx and Docutils.

Given we are somewhat likely to change the specification in Docutils, I would say that this is not a bug and that when possible Sphinx will make this more explicit by setting the include root.

A

[dstadelm]

Hi A

Thank you for the response. Although I'm somewhat disheartened to here it. If I understand you correctly this will imply that for every file you have to know in which context it is (the path from the 'include root'). I prefer the way docutils is handeling it currently, so that any include (also images) is relative to the current file location.

My reasoning:

1. This makes reusability so much better as one can reuse 'sub' documentation elements without worrying about in what context they were written.
2. I am a strong advocate for keeping the documentation of software projects close to the code. I want the documentation in the source tree and not next to the source tree. There are several reasonings for this such as:

• reusability: because if a subdirectory shall be reused it can be extracted to a submodule and the documentation automatically is part of the new submodule
• maintainability: it is clear what documentation has to be updated if the source code is modified

The include behaviour you are describing is (again, I hope I understood you correctly), similar as asciidoctor with antora or latex is following. And I have the same gripe with them (at least in LaTeX there is a workaround with environment variables)

I'm sure you have reasons for the path you are following, and you might find reasons why my suggestion has its flaws. Could you point out where my proposals fail, or if it might be possible to make Sphinx configurable to allow for both behaviors.

Regards and utter most respect for the great work on Sphinx