Deprecate get_matching_docs()

CHANGES

@@ -23,6 +23,7 @@ Deprecated
 * The string style ``base`` argument of ``env.doc2path()`` is deprecated.
 * ``sphinx.ext.doctest.doctest_encode()``
 * ``sphinx.testing.util.remove_unicode_literal()``
+* ``sphinx.util.get_matching_docs()`` is deprecated
 * ``sphinx.util.osutil.walk()``
 * ``translatablestrings`` variable for LaTeX template
 

doc/extdev/index.rst

@@ -143,6 +143,11 @@ The following is a list of deprecated interfaces.
      - 4.0
      - N/A
 
+   * - ``sphinx.util.get_matching_docs()``
+     - 2.0
+     - 4.0
+     - ``sphinx.util.get_matching_files()``
+
    * - ``sphinx.util.osutil.walk()``
      - 2.0
      - 4.0

sphinx/util/__init__.py

@@ -30,7 +30,7 @@ from docutils.utils import relative_path
 from six import text_type, binary_type
 from six.moves.urllib.parse import urlsplit, urlunsplit, quote_plus, parse_qsl, urlencode
 
-from sphinx.deprecation import RemovedInSphinx30Warning
+from sphinx.deprecation import RemovedInSphinx30Warning, RemovedInSphinx40Warning
 from sphinx.errors import PycodeError, SphinxParallelError, ExtensionError
 from sphinx.util import logging
 from sphinx.util.console import strip_colors, colorize, bold, term_width_line  # type: ignore
@@ -111,6 +111,8 @@ def get_matching_docs(dirname, suffixes, exclude_matchers=()):
 
     Exclude files and dirs matching a pattern in *exclude_patterns*.
     """
+    warnings.warn('get_matching_docs() is now deprecated. Use get_matching_files() instead.',
+                  RemovedInSphinx40Warning)
     suffixpatterns = ['*' + s for s in suffixes]
     for filename in get_matching_files(dirname, exclude_matchers):
         for suffixpattern in suffixpatterns: