Merge pull request #8043 from tk0miya/refactor_autodoc

refactor autodoc: Documenter.filter_members()
This commit is contained in:
Takeshi KOMIYA 2020-08-03 22:34:11 +09:00 committed by GitHub
commit a721631a54
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 39 additions and 15 deletions

View File

@ -10,6 +10,7 @@ Incompatible changes
Deprecated
----------
* ``sphinx.ext.autodoc.members_set_option()``
* ``sphinx.ext.autodoc.merge_special_members_option()``
* ``sphinx.writers.texinfo.TexinfoWriter.desc``
* C, parsing of pre-v3 style type directives and roles, along with the options

View File

@ -26,6 +26,11 @@ The following is a list of deprecated interfaces.
- (will be) Removed
- Alternatives
* - ``sphinx.ext.autodoc.members_set_option()``
- 3.2
- 5.0
- N/A
* - ``sphinx.ext.autodoc.merge_special_members_option()``
- 3.2
- 5.0

View File

@ -61,13 +61,29 @@ py_ext_sig_re = re.compile(
(?:\s* -> \s* (.*))? # return annotation
)? $ # and nothing more
''', re.VERBOSE)
special_member_re = re.compile(r'^__\S+__$')
def identity(x: Any) -> Any:
return x
ALL = object()
class _All:
"""A special value for :*-members: that matches to any member."""
def __contains__(self, item: Any) -> bool:
return True
class _Empty:
"""A special value for :exclude-members: that never matches to any member."""
def __contains__(self, item: Any) -> bool:
return False
ALL = _All()
EMPTY = _Empty()
UNINITIALIZED_ATTR = object()
INSTANCEATTR = object()
SLOTSATTR = object()
@ -82,11 +98,20 @@ def members_option(arg: Any) -> Union[object, List[str]]:
def members_set_option(arg: Any) -> Union[object, Set[str]]:
"""Used to convert the :members: option to auto directives."""
warnings.warn("members_set_option() is deprecated.",
RemovedInSphinx50Warning, stacklevel=2)
if arg is None:
return ALL
return {x.strip() for x in arg.split(',') if x.strip()}
def exclude_members_option(arg: Any) -> Union[object, Set[str]]:
"""Used to convert the :exclude-members: option."""
if arg is None:
return EMPTY
return {x.strip() for x in arg.split(',') if x.strip()}
def inherited_members_option(arg: Any) -> Union[object, Set[str]]:
"""Used to convert the :members: option to auto directives."""
if arg is None:
@ -647,29 +672,24 @@ class Documenter:
if safe_getattr(member, '__sphinx_mock__', False):
# mocked module or object
pass
elif (self.options.exclude_members not in (None, ALL) and
membername in self.options.exclude_members):
elif self.options.exclude_members and membername in self.options.exclude_members:
# remove members given by exclude-members
keep = False
elif want_all and membername.startswith('__') and \
membername.endswith('__') and len(membername) > 4:
elif want_all and special_member_re.match(membername):
# special __methods__
if self.options.special_members is ALL:
if self.options.special_members and membername in self.options.special_members:
if membername == '__doc__':
keep = False
elif is_filtered_inherited_member(membername):
keep = False
else:
keep = has_doc or self.options.undoc_members
elif self.options.special_members:
if membername in self.options.special_members:
keep = has_doc or self.options.undoc_members
else:
keep = False
elif (namespace, membername) in attr_docs:
if want_all and isprivate:
if self.options.private_members is None:
keep = False
elif self.options.private_members is ALL:
keep = True
else:
keep = membername in self.options.private_members
else:
@ -680,8 +700,6 @@ class Documenter:
if has_doc or self.options.undoc_members:
if self.options.private_members is None:
keep = False
elif self.options.private_members is ALL:
keep = True
elif is_filtered_inherited_member(membername):
keep = False
else:
@ -888,7 +906,7 @@ class ModuleDocumenter(Documenter):
'noindex': bool_option, 'inherited-members': inherited_members_option,
'show-inheritance': bool_option, 'synopsis': identity,
'platform': identity, 'deprecated': bool_option,
'member-order': member_order_option, 'exclude-members': members_set_option,
'member-order': member_order_option, 'exclude-members': exclude_members_option,
'private-members': members_option, 'special-members': members_option,
'imported-members': bool_option, 'ignore-module-all': bool_option
} # type: Dict[str, Callable]
@ -1308,7 +1326,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
'members': members_option, 'undoc-members': bool_option,
'noindex': bool_option, 'inherited-members': inherited_members_option,
'show-inheritance': bool_option, 'member-order': member_order_option,
'exclude-members': members_set_option,
'exclude-members': exclude_members_option,
'private-members': members_option, 'special-members': members_option,
} # type: Dict[str, Callable]