mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge pull request #8043 from tk0miya/refactor_autodoc
refactor autodoc: Documenter.filter_members()
This commit is contained in:
commit
a721631a54
1
CHANGES
1
CHANGES
@ -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
|
||||
|
@ -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
|
||||
|
@ -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]
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user