def get_doc(self, encoding=None):
content = self.env.config.autoclass_content
docstrings = []
attrdocstring = sage_getdoc_original(self.object)
if attrdocstring:
docstrings.append(attrdocstring)
# for classes, what the "docstring" is can be controlled via a
# config value; the default is only the class docstring
if content in ('both', 'init'):
initdocstring = sage_getdoc_original(
self.get_attr(self.object, '__init__', None))
# for new-style classes, no __init__ means default __init__
if initdocstring == object.__init__.__doc__:
initdocstring = None
if initdocstring:
if content == 'init':
docstrings = [initdocstring]
else:
docstrings.append(initdocstring)
doc = []
for docstring in docstrings:
if not isinstance(docstring, unicode):
docstring = force_decode(docstring, encoding)
doc.append(prepare_docstring(docstring))
return doc
def get_doc(self, encoding=None):
content = self.env.config.autoclass_content
docstrings = []
attrdocstring = sage_getdoc_original(self.object)
if attrdocstring:
docstrings.append(attrdocstring)
# for classes, what the "docstring" is can be controlled via a
# config value; the default is only the class docstring
if content in ('both', 'init'):
initdocstring = sage_getdoc_original(
self.get_attr(self.object, '__init__', None))
# for new-style classes, no __init__ means default __init__
if initdocstring == object.__init__.__doc__:
initdocstring = None
if initdocstring:
if content == 'init':
docstrings = [initdocstring]
else:
docstrings.append(initdocstring)
doc = []
for docstring in docstrings:
if not isinstance(docstring, unicode):
docstring = force_decode(docstring, encoding)
doc.append(prepare_docstring(docstring))
return doc
def can_document_member(cls, member, membername, isattr, parent):
# It can be documented if it is a genuine function.
# Often, a class instance has the same documentation as its class,
# and then we typically want to document the class and not the instance.
# However, there is an exception: CachedFunction(f) returns a class instance,
# whose doc string coincides with that of f and is thus different from
# that of the class CachedFunction. In that situation, we want that f is documented.
# This is part of SAGE TRAC 9976
return (isinstance(member, (FunctionType, BuiltinFunctionType))
or (isclassinstance(member)
and sage_getdoc_original(member) != sage_getdoc_original(member.__class__)))
def can_document_member(cls, member, membername, isattr, parent):
# It can be documented if it is a genuine function.
# Often, a class instance has the same documentation as its class,
# and then we typically want to document the class and not the instance.
# However, there is an exception: CachedFunction(f) returns a class instance,
# whose doc string coincides with that of f and is thus different from
# that of the class CachedFunction. In that situation, we want that f is documented.
# This is part of SAGE TRAC 9976
return (isinstance(member, (FunctionType, BuiltinFunctionType))
or (isclassinstance(member)
and sage_getdoc_original(member) != sage_getdoc_original(member.__class__)))
def get_doc(self, encoding=None):
"""Decode and return lines of the docstring(s) for the object."""
docstring = sage_getdoc_original(self.object)
if docstring:
# make sure we have Unicode docstrings, then sanitize and split
# into lines
return [prepare_docstring(force_decode(docstring, encoding))]
return []
def get_doc(self, encoding=None):
"""Decode and return lines of the docstring(s) for the object."""
docstring = sage_getdoc_original(self.object)
if docstring:
# make sure we have Unicode docstrings, then sanitize and split
# into lines
return [prepare_docstring(force_decode(docstring, encoding))]
return []
def filter_members(self, members, want_all):
"""
Filter the given member list: members are skipped if
- they are private (except if given explicitly)
- they are undocumented (except if undoc-members is given)
The user can override the skipping decision by connecting to the
``autodoc-skip-member`` event.
"""
ret = []
# search for members in source code too
namespace = '.'.join(self.objpath) # will be empty for modules
if self.analyzer:
attr_docs = self.analyzer.find_attr_docs()
else:
attr_docs = {}
# process members and determine which to skip
for (membername, member) in members:
# Immediately skip lazy imports to avoid deprecation
# messages (#17455).
if isinstance(member, LazyImport):
continue
# if isattr is True, the member is documented as an attribute
isattr = False
if want_all and membername.startswith('_'):
# ignore members whose name starts with _ by default
skip = True
elif (namespace, membername) in attr_docs:
# keep documented attributes
skip = False
isattr = True
else:
# ignore undocumented members if :undoc-members:
# is not given
doc = sage_getdoc_original(member)
skip = not self.options.undoc_members and not doc
# give the user a chance to decide whether this member
# should be skipped
if self.env.app:
# let extensions preprocess docstrings
skip_user = self.env.app.emit_firstresult(
'autodoc-skip-member', self.objtype, membername, member,
skip, self.options)
if skip_user is not None:
skip = skip_user
if skip:
continue
ret.append((membername, member, isattr))
return ret
def filter_members(self, members, want_all):
"""
Filter the given member list: members are skipped if
- they are private (except if given explicitly)
- they are undocumented (except if undoc-members is given)
The user can override the skipping decision by connecting to the
``autodoc-skip-member`` event.
"""
ret = []
# search for members in source code too
namespace = '.'.join(self.objpath) # will be empty for modules
if self.analyzer:
attr_docs = self.analyzer.find_attr_docs()
else:
attr_docs = {}
# process members and determine which to skip
for (membername, member) in members:
# Immediately skip lazy imports to avoid deprecation
# messages (#17455).
if isinstance(member, LazyImport):
continue
# if isattr is True, the member is documented as an attribute
isattr = False
if want_all and membername.startswith('_'):
# ignore members whose name starts with _ by default
skip = True
elif (namespace, membername) in attr_docs:
# keep documented attributes
skip = False
isattr = True
else:
# ignore undocumented members if :undoc-members:
# is not given
doc = sage_getdoc_original(member)
skip = not self.options.undoc_members and not doc
# give the user a chance to decide whether this member
# should be skipped
if self.env.app:
# let extensions preprocess docstrings
skip_user = self.env.app.emit_firstresult(
'autodoc-skip-member', self.objtype, membername, member,
skip, self.options)
if skip_user is not None:
skip = skip_user
if skip:
continue
ret.append((membername, member, isattr))
return ret
