From 1ba671a6771be858078207d5d8848f7962417b07 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 3 May 2020 01:59:47 +0900 Subject: [PATCH] Deprecate ignore parameter for Documenter.get_doc() --- CHANGES | 2 ++ doc/extdev/deprecated.rst | 10 ++++++++++ sphinx/ext/autodoc/__init__.py | 16 ++++++++++++---- sphinx/util/docstrings.py | 11 ++++++++++- 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 eae199b33..15050746f 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