From 491d0406df56556a48a2a6ceda84e27c13814eb2 Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Thu, 15 Feb 2018 14:07:29 +0900
Subject: [PATCH] Deprecate get_matching_docs()

---
 CHANGES                 | 1 +
 doc/extdev/index.rst    | 5 +++++
 sphinx/util/__init__.py | 4 +++-
 3 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/CHANGES b/CHANGES
index 5e8d7cb3b..ebb7c69ec 100644
--- a/CHANGES
+++ b/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
 
diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
index 423546c36..0039c8f2d 100644
--- a/doc/extdev/index.rst
+++ b/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
diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py
index 8bb18debd..8ea5641c9 100644
--- a/sphinx/util/__init__.py
+++ b/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: