Update include_patterns implementation (#10680)

doc/usage/configuration.rst

@@ -233,9 +233,6 @@ General configuration
    - ``'**/doc'`` -- all ``doc`` directories (this might be useful if
      documentation is co-located with source files)
 
-   :confval:`include_patterns` is also consulted when looking for static files
-   in :confval:`html_static_path` and :confval:`html_extra_path`.
-
    .. versionadded:: 5.1
 
 .. confval:: templates_path

sphinx/builders/html/__init__.py

@@ -840,8 +840,7 @@ class StandaloneHTMLBuilder(Builder):
             logger.warning(__('Failed to copy a file in html_static_file: %s: %r'),
                            filename, error)
 
-        excluded = Matcher(self.config.exclude_patterns + ["**/.*"],
+        excluded = Matcher(self.config.exclude_patterns + ["**/.*"])
-                           self.config.include_patterns)
         for entry in self.config.html_static_path:
             copy_asset(path.join(self.confdir, entry),
                        path.join(self.outdir, '_static'),
@@ -881,7 +880,7 @@ class StandaloneHTMLBuilder(Builder):
         """copy html_extra_path files."""
         try:
             with progress_message(__('copying extra files')):
-                excluded = Matcher(self.config.exclude_patterns, self.config.include_patterns)
+                excluded = Matcher(self.config.exclude_patterns)
                 for extra_path in self.config.html_extra_path:
                     entry = path.join(self.confdir, extra_path)
                     copy_asset(entry, self.outdir, excluded)

sphinx/directives/other.py

@@ -84,7 +84,7 @@ class TocTree(SphinxDirective):
         all_docnames.remove(self.env.docname)  # remove current document
 
         ret: List[Node] = []
-        excluded = Matcher(self.config.exclude_patterns, self.config.include_patterns)
+        excluded = Matcher(self.config.exclude_patterns)
         for entry in self.content:
             if not entry:
                 continue

sphinx/environment/adapters/toctree.py

@@ -74,7 +74,8 @@ class TocTree:
         # interactions between marking and pruning the tree (see bug #1046).
 
         toctree_ancestors = self.get_toctree_ancestors(docname)
-        excluded = Matcher(self.env.config.exclude_patterns, self.env.config.include_patterns)
+        included = Matcher(self.env.config.include_patterns)
+        excluded = Matcher(self.env.config.exclude_patterns)
 
         def _toctree_add_classes(node: Element, depth: int) -> None:
             """Add 'toctree-l%d' and 'current' classes to the toctree."""
@@ -166,6 +167,8 @@ class TocTree:
                     # this is raised if the included file does not exist
                     if excluded(self.env.doc2path(ref, False)):
                         message = __('toctree contains reference to excluded document %r')
+                    elif not included(self.env.doc2path(ref, False)):
+                        message = __('toctree contains reference to non-included document %r')
                     else:
                         message = __('toctree contains reference to nonexisting document %r')
 

sphinx/ext/autosummary/__init__.py

@@ -237,7 +237,7 @@ class Autosummary(SphinxDirective):
 
             tree_prefix = self.options['toctree'].strip()
             docnames = []
-            excluded = Matcher(self.config.exclude_patterns, self.config.include_patterns)
+            excluded = Matcher(self.config.exclude_patterns)
             filename_map = self.config.autosummary_filename_map
             for _name, _sig, _summary, real_name in items:
                 real_name = filename_map.get(real_name, real_name)

sphinx/project.py

@@ -38,8 +38,8 @@ class Project:
         self.docnames = set()
         for filename in get_matching_files(
             self.srcdir,
-            [*exclude_paths] + EXCLUDE_PATHS,
             include_paths,
+            [*exclude_paths] + EXCLUDE_PATHS,
         ):
             docname = self.path2doc(filename)
             if docname:

sphinx/util/matching.py

@@ -64,8 +64,7 @@ class Matcher:
           For example, "**/index.rst" matches with "index.rst"
     """
 
-    def __init__(self, exclude_patterns: Iterable[str],
+    def __init__(self, exclude_patterns: Iterable[str]) -> None:
-                 include_patterns: Iterable[str] = ()) -> None:
         expanded = [pat[3:] for pat in exclude_patterns if pat.startswith('**/')]
         self.patterns = compile_matchers(list(exclude_patterns) + expanded)
 
@@ -105,8 +104,8 @@ def patfilter(names: Iterable[str], pat: str) -> List[str]:
 
 def get_matching_files(
     dirname: str,
+    include_patterns: Iterable[str] = ("**",),
     exclude_patterns: Iterable[str] = (),
-    include_patterns: Iterable[str] = ("**",)
 ) -> Iterator[str]:
     """Get all file names in a directory, recursively.
 

tests/test_util_matching.py

@@ -98,7 +98,7 @@ def test_get_matching_files_all(rootdir):
 
 
 def test_get_matching_files_all_exclude_single(rootdir):
-    files = get_matching_files(rootdir / "test-root", ["**.html"])
+    files = get_matching_files(rootdir / "test-root", exclude_patterns=["**.html"])
     assert sorted(files) == [
         'Makefile', 'autodoc.txt', 'autodoc_target.py', 'bom.txt', 'conf.py',
         'extapi.txt', 'extensions.txt', 'file_with_special_#_chars.xyz', 'footnote.txt',
@@ -112,7 +112,7 @@ def test_get_matching_files_all_exclude_single(rootdir):
 
 
 def test_get_matching_files_all_exclude_multiple(rootdir):
-    files = get_matching_files(rootdir / "test-root", ["**.html", "**.inc"])
+    files = get_matching_files(rootdir / "test-root", exclude_patterns=["**.html", "**.inc"])
     assert sorted(files) == [
         'Makefile', 'autodoc.txt', 'autodoc_target.py', 'bom.txt', 'conf.py',
         'extapi.txt', 'extensions.txt', 'file_with_special_#_chars.xyz', 'footnote.txt',
@@ -125,7 +125,7 @@ def test_get_matching_files_all_exclude_multiple(rootdir):
 
 
 def test_get_matching_files_all_exclude_nonexistent(rootdir):
-    files = get_matching_files(rootdir / "test-root", ["halibut/**"])
+    files = get_matching_files(rootdir / "test-root", exclude_patterns=["halibut/**"])
     assert sorted(files) == [
         'Makefile', '_templates/contentssb.html', '_templates/customsb.html',
         '_templates/layout.html', 'autodoc.txt', 'autodoc_target.py', 'bom.txt', 'conf.py',
@@ -140,7 +140,7 @@ def test_get_matching_files_all_exclude_nonexistent(rootdir):
 
 
 def test_get_matching_files_all_include_single(rootdir):
-    files = get_matching_files(rootdir / "test-root", [], ["subdir/**"])
+    files = get_matching_files(rootdir / "test-root", include_patterns=["subdir/**"])
     assert sorted(files) == [
         'subdir/excluded.txt', 'subdir/images.txt', 'subdir/img.png', 'subdir/include.inc',
         'subdir/includes.txt', 'subdir/simg.png',
@@ -148,7 +148,7 @@ def test_get_matching_files_all_include_single(rootdir):
 
 
 def test_get_matching_files_all_include_multiple(rootdir):
-    files = get_matching_files(rootdir / "test-root", [], ["special/**", "subdir/**"])
+    files = get_matching_files(rootdir / "test-root", include_patterns=["special/**", "subdir/**"])
     assert sorted(files) == [
         'special/api.h', 'special/code.py', 'subdir/excluded.txt', 'subdir/images.txt',
         'subdir/img.png', 'subdir/include.inc', 'subdir/includes.txt', 'subdir/simg.png',
@@ -156,19 +156,19 @@ def test_get_matching_files_all_include_multiple(rootdir):
 
 
 def test_get_matching_files_all_include_nonexistent(rootdir):
-    files = get_matching_files(rootdir / "test-root", [], ["halibut/**"])
+    files = get_matching_files(rootdir / "test-root", include_patterns=["halibut/**"])
     assert sorted(files) == []
 
 
 def test_get_matching_files_all_include_prefix(rootdir):
-    files = get_matching_files(rootdir / "test-root", [], ["autodoc*"])
+    files = get_matching_files(rootdir / "test-root", include_patterns=["autodoc*"])
     assert sorted(files) == [
         'autodoc.txt', 'autodoc_target.py',
     ]
 
 
 def test_get_matching_files_all_include_question_mark(rootdir):
-    files = get_matching_files(rootdir / "test-root", [], ["img.???"])
+    files = get_matching_files(rootdir / "test-root", include_patterns=["img.???"])
     assert sorted(files) == [
         'img.gif', 'img.pdf', 'img.png',
     ]