IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #9518 from jbms/fix-autodoc-docstring-signature-for-init-and-new

Browse Source 
Fix autodoc_docstring_signature support for __init__ and __new__
This commit is contained in:
Takeshi KOMIYA 2021-08-02 00:25:39 +09:00 committed by GitHub
commit 1cdde3df18
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 71 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
sphinx/ext/autodoc/__init__.py
View File

@ -2234,6 +2234,12 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
return None
def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
if self._new_docstrings is not None:
# docstring already returned previously, then modified by
# `DocstringSignatureMixin`. Just return the previously-computed
# result, so that we don't lose the processing done by
# `DocstringSignatureMixin`.
return self._new_docstrings
if self.objpath[-1] == '__init__':
docstring = getdoc(self.object, self.get_attr,
self.config.autodoc_inherit_docstrings,
@ -2248,15 +2254,13 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
else:
return []
elif self.objpath[-1] == '__new__':
__new__ = self.get_attr(self.object, '__new__', None)
if __new__:
docstring = getdoc(__new__, self.get_attr,
self.config.autodoc_inherit_docstrings,
self.parent, self.object_name)
if (docstring is not None and
(docstring == object.__new__.__doc__ or # for pypy
docstring.strip() == object.__new__.__doc__)): # for !pypy
docstring = None
docstring = getdoc(self.object, self.get_attr,
self.config.autodoc_inherit_docstrings,
self.parent, self.object_name)
if (docstring is not None and
(docstring == object.__new__.__doc__ or # for pypy
docstring.strip() == object.__new__.__doc__)): # for !pypy
docstring = None
if docstring:
tab_width = self.directive.state.document.settings.tab_width
return [prepare_docstring(docstring, tabsize=tab_width)]

14
tests/roots/test-ext-autodoc/target/__init__.py
View File

@ -114,6 +114,20 @@ class InnerChild(Outer.Inner):
class DocstringSig(object):
def __new__(cls, *new_args, **new_kwargs):
"""__new__(cls, d, e=1) -> DocstringSig
First line of docstring
rest of docstring
"""
def __init__(self, *init_args, **init_kwargs):
"""__init__(self, a, b=1) -> None
First line of docstring
rest of docstring
"""
def meth(self):
"""meth(FOO, BAR=1) -> BAZ
First line of docstring

47
tests/test_ext_autodoc_configs.py
View File

@ -287,14 +287,34 @@ def test_autodoc_inherit_docstrings(app):
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_autodoc_docstring_signature(app):
options = {"members": None}
options = {"members": None, "special-members": "__init__, __new__"}
actual = do_autodoc(app, 'class', 'target.DocstringSig', options)
assert list(actual) == [
'',
'.. py:class:: DocstringSig()',
# FIXME: Ideally this would instead be: `DocstringSig(d, e=1)` but
# currently `ClassDocumenter` does not apply the docstring signature
# logic when extracting a signature from a __new__ or __init__ method.
'.. py:class:: DocstringSig(*new_args, **new_kwargs)',
' :module: target',
'',
'',
' .. py:method:: DocstringSig.__init__(self, a, b=1) -> None',
' :module: target',
'',
' First line of docstring',
'',
' rest of docstring',
'',
'',
' .. py:method:: DocstringSig.__new__(cls, d, e=1) -> DocstringSig',
' :module: target',
' :staticmethod:',
'',
' First line of docstring',
'',
' rest of docstring',
'',
'',
' .. py:method:: DocstringSig.meth(FOO, BAR=1) -> BAZ',
' :module: target',
'',
@ -331,10 +351,31 @@ def test_autodoc_docstring_signature(app):
actual = do_autodoc(app, 'class', 'target.DocstringSig', options)
assert list(actual) == [
'',
'.. py:class:: DocstringSig()',
'.. py:class:: DocstringSig(*new_args, **new_kwargs)',
' :module: target',
'',
'',
' .. py:method:: DocstringSig.__init__(*init_args, **init_kwargs)',
' :module: target',
'',
' __init__(self, a, b=1) -> None',
' First line of docstring',
'',
' rest of docstring',
'',
'',
'',
' .. py:method:: DocstringSig.__new__(cls, *new_args, **new_kwargs)',
' :module: target',
' :staticmethod:',
'',
' __new__(cls, d, e=1) -> DocstringSig',
' First line of docstring',
'',
' rest of docstring',
'',
'',
'',
' .. py:method:: DocstringSig.meth()',
' :module: target',
'',