Merge pull request #7598 from tk0miya/deprecate_ignore

Deprecate ignore parameter for Documenter.get_doc()

4 files changed, 34 insertions, 5 deletions

diff --git a/CHANGES b/CHANGES
index 6eef931e3..24c30fbac 100644
--- a/CHANGES
+++ b/CHANGES
@@ -16,6 +16,7 @@ Deprecated
   been changed to Sphinx object
 * ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` takes an object type
   as an argument
+* The ``ignore`` argument of ``sphinx.ext.autodoc.Documenter.get_doc()``
 * The ``template_dir`` argument of ``sphinx.ext.autosummary.generate.
   AutosummaryRenderer``
 * The ``module`` argument of ``sphinx.ext.autosummary.generate.
@@ -24,6 +25,7 @@ Deprecated
   generate_autosummary_docs()``
 * The ``template_dir`` argument of ``sphinx.ext.autosummary.generate.
   generate_autosummary_docs()``
+* The ``ignore`` argument of ``sphinx.util.docstring.prepare_docstring()``
 * ``sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()``
 
 Features added
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index 35c7ec96a..9d05f894b 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -39,6 +39,11 @@ The following is a list of deprecated interfaces.
      - 5.0
      - N/A
 
+   * - The ``ignore`` argument of ``sphinx.ext.autodoc.Documenter.get_doc()``
+     - 3.1
+     - 5.0
+     - N/A
+
    * - The ``template_dir`` argument of
        ``sphinx.ext.autosummary.generate.AutosummaryRenderer``
      - 3.1
@@ -68,6 +73,11 @@ The following is a list of deprecated interfaces.
      - 5.0
      - N/A
 
+   * - The ``ignore`` argument of ``sphinx.util.docstring.prepare_docstring()``
+     - 3.1
+     - 5.0
+     - N/A
+
    * - ``desc_signature['first']``
      -
      - 3.0
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index 29bfb791c..609928422 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -429,12 +429,16 @@ class Documenter:
             # etc. don't support a prepended module name
             self.add_line('   :module: %s' % self.modname, sourcename)
 
-    def get_doc(self, encoding: str = None, ignore: int = 1) -> List[List[str]]:
+    def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
         """Decode and return lines of the docstring(s) for the object."""
         if encoding is not None:
             warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated."
                           % self.__class__.__name__,
                           RemovedInSphinx40Warning)
+        if ignore is not None:
+            warnings.warn("The 'ignore' argument to autodoc.%s.get_doc() is deprecated."
+                          % self.__class__.__name__,
+                          RemovedInSphinx50Warning, stacklevel=2)
         docstring = getdoc(self.object, self.get_attr,
                            self.env.config.autodoc_inherit_docstrings,
                            self.parent, self.object_name)
@@ -979,7 +983,7 @@ class DocstringSignatureMixin:
             break
         return result
 
-    def get_doc(self, encoding: str = None, ignore: int = 1) -> List[List[str]]:
+    def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
         if encoding is not None:
             warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated."
                           % self.__class__.__name__,
@@ -1239,7 +1243,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
                 self.add_line('   ' + _('Bases: %s') % ', '.join(bases),
                               sourcename)
 
-    def get_doc(self, encoding: str = None, ignore: int = 1) -> List[List[str]]:
+    def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
         if encoding is not None:
             warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated."
                           % self.__class__.__name__,
@@ -1736,8 +1740,12 @@ class SlotsAttributeDocumenter(AttributeDocumenter):
                 self.env.note_reread()
                 return False
 
-    def get_doc(self, encoding: str = None, ignore: int = 1) -> List[List[str]]:
+    def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
         """Decode and return lines of the docstring(s) for the object."""
+        if ignore is not None:
+            warnings.warn("The 'ignore' argument to autodoc.%s.get_doc() is deprecated."
+                          % self.__class__.__name__,
+                          RemovedInSphinx50Warning, stacklevel=2)
         name = self.objpath[-1]
         __slots__ = safe_getattr(self.parent, '__slots__', [])
         if isinstance(__slots__, dict) and isinstance(__slots__.get(name), str):
diff --git a/sphinx/util/docstrings.py b/sphinx/util/docstrings.py
index 7b3f011d1..64fdbf1d7 100644
--- a/sphinx/util/docstrings.py
+++ b/sphinx/util/docstrings.py
@@ -10,10 +10,13 @@
 
 import re
 import sys
+import warnings
 from typing import Dict, List
 
 from docutils.parsers.rst.states import Body
 
+from sphinx.deprecation import RemovedInSphinx50Warning
+
 
 field_list_item_re = re.compile(Body.patterns['field_marker'])
 
@@ -42,7 +45,7 @@ def extract_metadata(s: str) -> Dict[str, str]:
     return metadata
 
 
-def prepare_docstring(s: str, ignore: int = 1, tabsize: int = 8) -> List[str]:
+def prepare_docstring(s: str, ignore: int = None, tabsize: int = 8) -> List[str]:
     """Convert a docstring into lines of parseable reST.  Remove common leading
     indentation, where the indentation of a given number of lines (usually just
     one) is ignored.
@@ -51,6 +54,12 @@ def prepare_docstring(s: str, ignore: int = 1, tabsize: int = 8) -> List[str]:
     ViewList (used as argument of nested_parse().)  An empty line is added to
     act as a separator between this docstring and following content.
     """
+    if ignore is None:
+        ignore = 1
+    else:
+        warnings.warn("The 'ignore' argument to parepare_docstring() is deprecated.",
+                      RemovedInSphinx50Warning, stacklevel=2)
+
     lines = s.expandtabs(tabsize).splitlines()
     # Find minimum indentation of any non-blank lines after ignored lines.
     margin = sys.maxsize