def get_doc(self, encoding=None):
"""Decode and return lines of the docstring(s) for the object."""
docstring = _sage_getdoc_unformatted(self.object) #self.get_attr(self.object, '__doc__', None)
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:
# 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_unformatted(member) #self.get_attr(member, '__doc__', None)
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 get_doc(self, encoding=None):
content = self.env.config.autoclass_content
docstrings = []
docstring = _sage_getdoc_unformatted(self.object) #self.get_attr(self.object, '__doc__', None)
if docstring:
docstrings.append(docstring)
# 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_unformatted( #self.get_attr(
self.get_attr(self.object, '__init__', None))#, '__doc__')
# 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)
return [prepare_docstring(force_decode(docstring, encoding))
for docstring in docstrings]
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_unformatted(member)!=_sage_getdoc_unformatted(member.__class__))