mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
autodoc: minor PEP8 adjustments
This commit is contained in:
Georg Brandl
parent
062492d75f
commit
57e897669d
@ -30,7 +30,7 @@ from sphinx.application import ExtensionError
|
||||
from sphinx.util.nodes import nested_parse_with_titles
|
||||
from sphinx.util.compat import Directive
|
||||
from sphinx.util.inspect import getargspec, isdescriptor, safe_getmembers, \
|
||||
safe_getattr, safe_repr, is_builtin_class_method
|
||||
safe_getattr, safe_repr, is_builtin_class_method
|
||||
from sphinx.util.docstrings import prepare_docstring
|
||||
|
||||
|
||||
@ -50,11 +50,13 @@ class DefDict(dict):
|
||||
def __init__(self, default):
|
||||
dict.__init__(self)
|
||||
self.default = default
|
||||
|
||||
def __getitem__(self, key):
|
||||
try:
|
||||
return dict.__getitem__(self, key)
|
||||
except KeyError:
|
||||
return self.default
|
||||
|
||||
def __bool__(self):
|
||||
# docutils check "if option_spec"
|
||||
return True
|
||||
@ -92,6 +94,7 @@ class _MockModule(object):
|
||||
else:
|
||||
return _MockModule()
|
||||
|
||||
|
||||
def mock_import(modname):
|
||||
if '.' in modname:
|
||||
pkg, _n, mods = modname.rpartition('.')
|
||||
@ -104,12 +107,14 @@ def mock_import(modname):
|
||||
ALL = object()
|
||||
INSTANCEATTR = object()
|
||||
|
||||
|
||||
def members_option(arg):
|
||||
"""Used to convert the :members: option to auto directives."""
|
||||
if arg is None:
|
||||
return ALL
|
||||
return [x.strip() for x in arg.split(',')]
|
||||
|
||||
|
||||
def members_set_option(arg):
|
||||
"""Used to convert the :members: option to auto directives."""
|
||||
if arg is None:
|
||||
@ -118,6 +123,7 @@ def members_set_option(arg):
|
||||
|
||||
SUPPRESS = object()
|
||||
|
||||
|
||||
def annotation_option(arg):
|
||||
if arg is None:
|
||||
# suppress showing the representation of the object
|
||||
@ -125,6 +131,7 @@ def annotation_option(arg):
|
||||
else:
|
||||
return arg
|
||||
|
||||
|
||||
def bool_option(arg):
|
||||
"""Used to convert flag options to auto directives. (Instead of
|
||||
directives.flag(), which returns None).
|
||||
@ -201,6 +208,7 @@ def cut_lines(pre, post=0, what=None):
|
||||
lines.append('')
|
||||
return process
|
||||
|
||||
|
||||
def between(marker, what=None, keepempty=False, exclude=False):
|
||||
"""Return a listener that either keeps, or if *exclude* is True excludes,
|
||||
lines between lines that match the *marker* regular expression. If no line
|
||||
@ -211,6 +219,7 @@ def between(marker, what=None, keepempty=False, exclude=False):
|
||||
be processed.
|
||||
"""
|
||||
marker_re = re.compile(marker)
|
||||
|
||||
def process(app, what_, name, obj, options, lines):
|
||||
if what and what_ not in what:
|
||||
return
|
||||
@ -325,7 +334,7 @@ class Documenter(object):
|
||||
# an autogenerated one
|
||||
try:
|
||||
explicit_modname, path, base, args, retann = \
|
||||
py_ext_sig_re.match(self.name).groups()
|
||||
py_ext_sig_re.match(self.name).groups()
|
||||
except AttributeError:
|
||||
self.directive.warn('invalid signature for auto%s (%r)' %
|
||||
(self.objtype, self.name))
|
||||
@ -340,7 +349,7 @@ class Documenter(object):
|
||||
parents = []
|
||||
|
||||
self.modname, self.objpath = \
|
||||
self.resolve_name(modname, parents, path, base)
|
||||
self.resolve_name(modname, parents, path, base)
|
||||
|
||||
if not self.modname:
|
||||
return False
|
||||
@ -637,19 +646,19 @@ class Documenter(object):
|
||||
|
||||
keep = False
|
||||
if want_all and membername.startswith('__') and \
|
||||
membername.endswith('__') and len(membername) > 4:
|
||||
membername.endswith('__') and len(membername) > 4:
|
||||
# special __methods__
|
||||
if self.options.special_members is ALL and \
|
||||
membername != '__doc__':
|
||||
keep = has_doc or self.options.undoc_members
|
||||
elif self.options.special_members and \
|
||||
self.options.special_members is not ALL and \
|
||||
self.options.special_members is not ALL and \
|
||||
membername in self.options.special_members:
|
||||
keep = has_doc or self.options.undoc_members
|
||||
elif want_all and membername.startswith('_'):
|
||||
# ignore members whose name starts with _ by default
|
||||
keep = self.options.private_members and \
|
||||
(has_doc or self.options.undoc_members)
|
||||
(has_doc or self.options.undoc_members)
|
||||
elif (namespace, membername) in attr_docs:
|
||||
# keep documented attributes
|
||||
keep = True
|
||||
@ -685,7 +694,7 @@ class Documenter(object):
|
||||
self.env.temp_data['autodoc:class'] = self.objpath[0]
|
||||
|
||||
want_all = all_members or self.options.inherited_members or \
|
||||
self.options.members is ALL
|
||||
self.options.members is ALL
|
||||
# find out which members are documentable
|
||||
members_check_module, members = self.get_object_members(want_all)
|
||||
|
||||
@ -707,11 +716,11 @@ class Documenter(object):
|
||||
# give explicitly separated module name, so that members
|
||||
# of inner classes can be documented
|
||||
full_mname = self.modname + '::' + \
|
||||
'.'.join(self.objpath + [mname])
|
||||
'.'.join(self.objpath + [mname])
|
||||
documenter = classes[-1](self.directive, full_mname, self.indent)
|
||||
memberdocumenters.append((documenter, isattr))
|
||||
member_order = self.options.member_order or \
|
||||
self.env.config.autodoc_member_order
|
||||
self.env.config.autodoc_member_order
|
||||
if member_order == 'groupwise':
|
||||
# sort by group; relies on stable sort to keep items in the
|
||||
# same group sorted alphabetically
|
||||
@ -719,6 +728,7 @@ class Documenter(object):
|
||||
elif member_order == 'bysource' and self.analyzer:
|
||||
# sort by source order, by virtue of the module analyzer
|
||||
tagorder = self.analyzer.tagorder
|
||||
|
||||
def keyfunc(entry):
|
||||
fullname = entry[0].name.split('::')[1]
|
||||
return tagorder.get(fullname, len(tagorder))
|
||||
@ -872,7 +882,7 @@ class ModuleDocumenter(Documenter):
|
||||
self.directive.warn(
|
||||
'missing attribute mentioned in :members: or __all__: '
|
||||
'module %s, attribute %s' % (
|
||||
safe_getattr(self.object, '__name__', '???'), mname))
|
||||
safe_getattr(self.object, '__name__', '???'), mname))
|
||||
return False, ret
|
||||
|
||||
|
||||
@ -976,6 +986,7 @@ class DocstringSignatureMixin(object):
|
||||
self.args, self.retann = result
|
||||
return Documenter.format_signature(self)
|
||||
|
||||
|
||||
class DocstringStripSignatureMixin(DocstringSignatureMixin):
|
||||
"""
|
||||
Mixin for AttributeDocumenter to provide the
|
||||
@ -1007,7 +1018,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):
|
||||
|
||||
def format_args(self):
|
||||
if inspect.isbuiltin(self.object) or \
|
||||
inspect.ismethoddescriptor(self.object):
|
||||
inspect.ismethoddescriptor(self.object):
|
||||
# cannot introspect arguments of a C function or method
|
||||
return None
|
||||
try:
|
||||
@ -1070,8 +1081,8 @@ class ClassDocumenter(ModuleLevelDocumenter):
|
||||
# classes without __init__ method, default __init__ or
|
||||
# __init__ written in C?
|
||||
if initmeth is None or \
|
||||
is_builtin_class_method(self.object, '__init__') or \
|
||||
not(inspect.ismethod(initmeth) or inspect.isfunction(initmeth)):
|
||||
is_builtin_class_method(self.object, '__init__') or \
|
||||
not(inspect.ismethod(initmeth) or inspect.isfunction(initmeth)):
|
||||
return None
|
||||
try:
|
||||
argspec = getargspec(initmeth)
|
||||
@ -1142,7 +1153,7 @@ class ClassDocumenter(ModuleLevelDocumenter):
|
||||
# for new-style classes, no __init__ means default __init__
|
||||
if (initdocstring is not None and
|
||||
(initdocstring == object.__init__.__doc__ or # for pypy
|
||||
initdocstring.strip() == object.__init__.__doc__)): #for !pypy
|
||||
initdocstring.strip() == object.__init__.__doc__)): # for !pypy
|
||||
initdocstring = None
|
||||
if initdocstring:
|
||||
if content == 'init':
|
||||
@ -1186,7 +1197,7 @@ class ExceptionDocumenter(ClassDocumenter):
|
||||
@classmethod
|
||||
def can_document_member(cls, member, membername, isattr, parent):
|
||||
return isinstance(member, class_types) and \
|
||||
issubclass(member, BaseException)
|
||||
issubclass(member, BaseException)
|
||||
|
||||
|
||||
class DataDocumenter(ModuleLevelDocumenter):
|
||||
@ -1233,7 +1244,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):
|
||||
@classmethod
|
||||
def can_document_member(cls, member, membername, isattr, parent):
|
||||
return inspect.isroutine(member) and \
|
||||
not isinstance(parent, ModuleDocumenter)
|
||||
not isinstance(parent, ModuleDocumenter)
|
||||
|
||||
def import_object(self):
|
||||
ret = ClassLevelDocumenter.import_object(self)
|
||||
@ -1257,7 +1268,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):
|
||||
|
||||
def format_args(self):
|
||||
if inspect.isbuiltin(self.object) or \
|
||||
inspect.ismethoddescriptor(self.object):
|
||||
inspect.ismethoddescriptor(self.object):
|
||||
# can never get arguments of a C function or method
|
||||
return None
|
||||
argspec = getargspec(self.object)
|
||||
@ -1272,7 +1283,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):
|
||||
pass
|
||||
|
||||
|
||||
class AttributeDocumenter(DocstringStripSignatureMixin,ClassLevelDocumenter):
|
||||
class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):
|
||||
"""
|
||||
Specialized Documenter subclass for attributes.
|
||||
"""
|
||||
@ -1290,9 +1301,9 @@ class AttributeDocumenter(DocstringStripSignatureMixin,ClassLevelDocumenter):
|
||||
@classmethod
|
||||
def can_document_member(cls, member, membername, isattr, parent):
|
||||
isdatadesc = isdescriptor(member) and not \
|
||||
isinstance(member, cls.method_types) and not \
|
||||
type(member).__name__ in ("type", "method_descriptor",
|
||||
"instancemethod")
|
||||
isinstance(member, cls.method_types) and not \
|
||||
type(member).__name__ in ("type", "method_descriptor",
|
||||
"instancemethod")
|
||||
return isdatadesc or (not isinstance(parent, ModuleDocumenter)
|
||||
and not inspect.isroutine(member)
|
||||
and not isinstance(member, class_types))
|
||||
@ -1303,7 +1314,7 @@ class AttributeDocumenter(DocstringStripSignatureMixin,ClassLevelDocumenter):
|
||||
def import_object(self):
|
||||
ret = ClassLevelDocumenter.import_object(self)
|
||||
if isdescriptor(self.object) and \
|
||||
not isinstance(self.object, self.method_types):
|
||||
not isinstance(self.object, self.method_types):
|
||||
self._datadescriptor = True
|
||||
else:
|
||||
# if it's not a data descriptor
|
||||
@ -1312,7 +1323,7 @@ class AttributeDocumenter(DocstringStripSignatureMixin,ClassLevelDocumenter):
|
||||
|
||||
def get_real_modname(self):
|
||||
return self.get_attr(self.parent or self.object, '__module__', None) \
|
||||
or self.modname
|
||||
or self.modname
|
||||
|
||||
def add_directive_header(self, sig):
|
||||
ClassLevelDocumenter.add_directive_header(self, sig)
|
||||
@ -1479,7 +1490,7 @@ def add_documenter(cls):
|
||||
raise ExtensionError('autodoc documenter %r must be a subclass '
|
||||
'of Documenter' % cls)
|
||||
# actually, it should be possible to override Documenters
|
||||
#if cls.objtype in AutoDirective._registry:
|
||||
# if cls.objtype in AutoDirective._registry:
|
||||
# raise ExtensionError('autodoc documenter for %r is already '
|
||||
# 'registered' % cls.objtype)
|
||||
AutoDirective._registry[cls.objtype] = cls
|
||||
|
||||
Loading…
Reference in New Issue
Block a user