From 8335d906f9701cf52dc2f42cb51eb75a7ec99cdf Mon Sep 17 00:00:00 2001 From: Jared Dillard Date: Tue, 25 Aug 2026 02:01:59 -0700 Subject: [PATCH 1/2] Document include-only reStructuredText files --- doc/usage/restructuredtext/basics.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index cd7a151b95a..59d2dbd89a2 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -400,6 +400,24 @@ Docutils supports the following directives: when given an absolute include file path, this directive takes it as relative to the source directory + Sphinx considers each file whose suffix is listed in + :confval:`source_suffix` to be a standalone source document, even if the + file is also included in another document. To use a file only as reusable + content, either give it a suffix that is not listed in ``source_suffix``, + such as :file:`.inc` or :file:`.rst.inc`, or exclude it from source + discovery. For example, to store reusable content in an + :file:`_includes` directory, add the following to :file:`conf.py`: + + .. code-block:: python + + exclude_patterns = ['_includes/**'] + + Files excluded by :confval:`exclude_patterns` can still be included, and + included content is parsed as reStructuredText regardless of its filename + extension. Without one of these measures, labels in an included file can + be registered both in the standalone document and in the including + document, resulting in duplicate-label warnings. + .. _rstclass: - :dudir:`class ` From 27555bd495655126e26f7b2c5b3f2c2c70fc3ec7 Mon Sep 17 00:00:00 2001 From: Jared Dillard Date: Tue, 25 Aug 2026 21:46:07 -0700 Subject: [PATCH 2/2] Clarify usage of file suffixes in Sphinx Corrected wording for clarity regarding file suffixes and inclusion in Sphinx documentation. --- doc/usage/restructuredtext/basics.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 59d2dbd89a2..bb2019e016c 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -402,11 +402,11 @@ Docutils supports the following directives: Sphinx considers each file whose suffix is listed in :confval:`source_suffix` to be a standalone source document, even if the - file is also included in another document. To use a file only as reusable + file is also included in another document. To use a file only as reusable content, either give it a suffix that is not listed in ``source_suffix``, - such as :file:`.inc` or :file:`.rst.inc`, or exclude it from source - discovery. For example, to store reusable content in an - :file:`_includes` directory, add the following to :file:`conf.py`: + such as :file:`.rsti`, or exclude it from source discovery. For example, + to store reusable content in an :file:`_includes` directory, add the + following to :file:`conf.py`: .. code-block:: python @@ -414,9 +414,7 @@ Docutils supports the following directives: Files excluded by :confval:`exclude_patterns` can still be included, and included content is parsed as reStructuredText regardless of its filename - extension. Without one of these measures, labels in an included file can - be registered both in the standalone document and in the including - document, resulting in duplicate-label warnings. + extension. .. _rstclass: