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

autodoc: minor PEP8 adjustments

Browse Source
This commit is contained in:
Georg Brandl 2014-09-22 10:54:20 +02:00
parent 062492d75f
commit 57e897669d
1 changed files with 35 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
sphinx/ext/autodoc.py
View File

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