.. include:: directive shouldn't care about filename extension

[brechtm]

index.rst:

.. |subst| replace:: Substitution

.. include:: a.rst

.. include:: b.rst

a.rst:

A: |subst|

b.rst:

B: |subst|

The output is correct:

A: Substitution

B: Substitution

But building the Sphinx projects yields these warnings:

a.rst:2: WARNING: Undefined substitution referenced: "subst".
b.rst:2: WARNING: Undefined substitution referenced: "subst".

Replacing the extension on a.rst and b.rst with .txt suppresses the warnings. This is apparently because Sphinx scans files with the .rst extension twice. I hope you agree that is very confusing, and the user should be able to use the .rst extension also for included files?

Environment info

• OS: Linux
• Python version: 3.6.9
• Sphinx version: 3.2.1

[tk0miya]

Yes. As you quoted, Sphinx processes all .rst files under the source directory. So the warnings are correct to me. What do you expect?

[brechtm]

My issue is that this is confusing behavior. How should the user know that they shouldn't use the .rst extension when .. include::ing a file? Why do they even need to think about this?

Sphinx simply shouldn't output a warning even if they included files have a .rst extension.

[tk0miya]

At present, Sphinx scans the target documents from the source directory by file extensions. After that, it reads them all. To prevent warnings (or skip processing), we need to know the "included" file before processing. How do we check it? I think it is hard to know until reading all of the target documents.

[delameter]

My issue is that this is confusing behavior. How should the user know that they shouldn't use the .rst extension when .. include::ing a file? Why do they even need to think about this?

Wow, thanks! That was the issue. Warnings were counter-intuitive insofar as possible. Changed extensions of files invoked by "include" to .rsti, it helped

[picnixz]

A future improvement could be that such warnings are delayed as much as possible but it's very difficult since it would require more post-processing (and won't be worth the effort most of the time).

With tk0miya's answer, I think this issue should be closed (you'll still get warnings/errors if you use rst documents like that, so it's an expected behaviour). However, I'll just change the labels and leave it open.

[jdillard]

Closing as expected behavior, but I made a docs PR, #14649, to give tips on how to avoid common issues if you want to give it a review.