def get_items(self, names):
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
ext_names = []
def process_obj(name, typ, include_public=None):
obj_name = name[name.index(':') + 1:]
full_name, obj, _, _ = import_by_name(obj_name, prefixes=prefixes)
members, _ = self.get_members(obj, typ, include_public)
ext_names.extend(
['~%s.%s' % (full_name, member) for member in members])
for elt in names:
if elt.startswith('methods:'):
process_obj(elt, 'method', ('__init__', ))
elif elt.startswith('methods_without_init:'):
process_obj(elt, 'method')
elif elt.startswith('attributes:'):
process_obj(elt, 'attribute')
elif elt.startswith('funcs:'):
process_obj(elt, 'function')
else:
ext_names.append(elt)
return super(ExtAutoSummary, self).get_items(ext_names)
def get_items(self, names):
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
items = []
prefix = ''
shorten = ''
def _get_items(name):
_items = super(AutoMemberSummary, self).get_items([shorten + name])
if self.result.data and ".. deprecated::" in self.result.data[0]:
# don't show deprecated classes / functions in summary
return
for dn, sig, summary, rn in _items:
if ".. deprecated::" in summary:
# don't show deprecated methods in summary
continue
items.append(('%s%s' % (prefix, dn), sig, summary, rn))
for name in names:
if '~' in name:
prefix, name = name.split('~')
shorten = '~'
else:
prefix = ''
shorten = ''
try:
real_name, obj, parent, _ = import_by_name(name,
prefixes=prefixes)
except ImportError:
self.warn('failed to import %s' % name)
continue
if not inspect.ismodule(obj):
_get_items(name)
continue
for member in dir(obj):
if member.startswith('_'):
continue
mobj = getattr(obj, member)
if hasattr(mobj, '__module__'):
if not mobj.__module__.startswith(real_name):
continue # skip imported classes & functions
elif hasattr(mobj, '__name__'):
continue # skip imported modules
else:
continue # skip instances
_get_items('%s.%s' % (mobj.__module__, member))
return items
def get_items(self, names):
"""
Subclass get items
to get support for all methods in an given object
"""
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
methodNames = []
for name in names:
methodNames.append(name)
_, obj, _, _ = import_by_name(name, prefixes=prefixes)
methodNames.extend(["%s.%s" % (name, method) for method in dir(obj) if not method.startswith("_")])
return super(AutosummaryMethodList, self).get_items(methodNames)
def get_items(self, names):
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
items = []
prefix = ''
shorten = ''
def _get_items(name):
_items = super(AutoMemberSummary, self).get_items([shorten + name])
if self.result.data and ".. deprecated::" in self.result.data[0]:
# don't show deprecated classes / functions in summary
return
for dn, sig, summary, rn in _items:
if ".. deprecated::" in summary:
# don't show deprecated methods in summary
continue
items.append(('%s%s' % (prefix, dn), sig, summary, rn))
for name in names:
if '~' in name:
prefix, name = name.split('~')
shorten = '~'
else:
prefix = ''
shorten = ''
try:
real_name, obj, parent, _ = import_by_name(name, prefixes=prefixes)
except ImportError:
self.warn('failed to import %s' % name)
continue
if not inspect.ismodule(obj):
_get_items(name)
continue
for member in dir(obj):
if member.startswith('_'):
continue
mobj = getattr(obj, member)
if hasattr(mobj, '__module__'):
if not mobj.__module__.startswith(real_name):
continue # skip imported classes & functions
elif hasattr(mobj, '__name__'):
continue # skip imported modules
else:
continue # skip instances
_get_items('%s.%s' % (mobj.__module__, member))
return items
def get_items(self,
names: List[str]) -> List[Tuple[str, str, str, str, str]]:
prefixes = get_import_prefixes_from_env(self.env)
items = super().get_items(names)
new_items = []
for name, item in zip(names, items):
if name.startswith("~"):
name = name[1:]
real_name, obj, parent, modname = import_by_name(name,
prefixes=prefixes)
config_type = find_config_type(obj)
new_items.append((item[0], item[1], item[2], item[3], config_type))
return new_items
def get_items(self, names):
"""
Subclass get items
to get support for all methods in an given object
"""
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
methodNames = []
for name in names:
methodNames.append(name)
_, obj, _, _ = import_by_name(name, prefixes=prefixes)
methodNames.extend([
"%s.%s" % (name, method) for method in dir(obj)
if not method.startswith("_")
])
return super(AutosummaryMethodList, self).get_items(methodNames)
def find_automembers(self):
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
objects = [import_by_name(p) for p in prefixes if p is not None]
new_names = []
for name, obj, _, _ in objects:
for attr, child in inspect.getmembers(obj):
if getattr(child, '__module__', None) != name:
continue
if inspect.isfunction(child):
new_names.append(attr)
elif inspect.isclass(child):
for childattr, grandchild in inspect.getmembers(child, inspect.isfunction):
if grandchild.__module__ != name:
continue
new_names.append('%s.%s' % (attr, childattr))
new_names.sort(key=lambda s: s.lower())
return new_names
def find_automembers(self):
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
objects = [import_by_name(p) for p in prefixes if p is not None]
new_names = []
for name, obj, _, _ in objects:
for attr, child in inspect.getmembers(obj):
if getattr(child, '__module__', None) != name:
continue
if inspect.isfunction(child):
new_names.append(attr)
elif inspect.isclass(child):
for childattr, grandchild in inspect.getmembers(
child, inspect.isfunction):
if grandchild.__module__ != name:
continue
new_names.append('%s.%s' % (attr, childattr))
new_names.sort(key=lambda s: s.lower())
return new_names
def fix_item(display_name, sig, summary, real_name):
class_names = {'TreeNode': 'tree', 'TabularMSA': 'msa'}
class_name = real_name.split('.')[-2]
if class_name in class_names:
nice_name = class_names[class_name]
else:
s1 = first_cap_re.sub(r'\1_\2', class_name)
nice_name = all_cap_re.sub(r'\1_\2', s1).lower()
if len(nice_name) > 10:
nice_name = ''.join([e[0] for e in nice_name.split('_')])
def fmt(string):
count = string.count('%s')
return string % tuple([nice_name] * count)
specials = {
'__eq__': fmt('%s1 == %s2'),
'__ne__': fmt('%s1 != %s2'),
'__gt__': fmt('%s1 > %s2'),
'__lt__': fmt('%s1 < %s2'),
'__ge__': fmt('%s1 >= %s2'),
'__le__': fmt('%s1 <= %s2'),
'__getitem__': fmt('%s[x]'),
'__iter__': fmt('iter(%s)'),
'__contains__': fmt('x in %s'),
'__bool__': fmt('bool(%s)'),
'__str__': fmt('str(%s)'),
'__reversed__': fmt('reversed(%s)'),
'__len__': fmt('len(%s)'),
'__copy__': fmt('copy.copy(%s)'),
'__deepcopy__': fmt('copy.deepcopy(%s)'),
}
if display_name in specials:
prefixes = autosummary.get_import_prefixes_from_env(self.env)
obj = autosummary.import_by_name(display_name,
prefixes=prefixes)
# Filter out any slot_wrappers that work their way in (more below)
if type(obj[1]).__name__ == 'wrapper_descriptor':
return None
return specials[display_name], '', summary, real_name
return display_name, sig, summary, real_name
def get_items(self, names):
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
ext_names = []
def process_obj(name, typ, include_public=None):
obj_name = name[name.index(':') + 1:]
full_name, obj, _, _ = import_by_name(obj_name, prefixes=prefixes)
members, _ = self.get_members(env.app, obj, typ, include_public)
ext_names.extend(['~%s.%s' % (full_name, member) for member in members])
for elt in names:
if elt.startswith('methods:'):
process_obj(elt, 'method', ('__init__',))
elif elt.startswith('methods_without_init:'):
process_obj(elt, 'method')
elif elt.startswith('attributes:'):
process_obj(elt, 'attribute')
elif elt.startswith('funcs:'):
process_obj(elt, 'function')
else:
ext_names.append(elt)
return super(ExtAutoSummary, self).get_items(ext_names)
def get_items(self, names):
"""Try to import the given names, and return a list of
``[(name, signature, summary_string, real_name), ...]``.
"""
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
items = []
max_item_chars = 50
for name in names:
display_name = name
if name.startswith('~'):
name = name[1:]
display_name = name.split('.')[-1]
try:
real_name, obj, parent = import_by_name(name,
prefixes=prefixes)
except ImportError:
self.warn('failed to import %s' % name)
items.append((name, '', '', name))
continue
# NB. using real_name here is important, since Documenters
# handle module prefixes slightly differently
documenter = get_documenter(obj, parent)(self, real_name)
if not documenter.parse_name():
self.warn('failed to parse name %s' % real_name)
items.append((display_name, '', '', real_name))
continue
if not documenter.import_object():
self.warn('failed to import object %s' % real_name)
items.append((display_name, '', '', real_name))
continue
display_name = documenter.format_name()
# -- Grab the signature
sig = documenter.format_signature()
if not sig:
sig = ''
else:
max_chars = max(10, max_item_chars - len(display_name))
sig = mangle_signature(sig, max_chars=max_chars)
sig = sig.replace('*', r'\*')
# -- Grab the summary
doc = list(documenter.process_doc(documenter.get_doc()))
while doc and not doc[0].strip():
doc.pop(0)
m = re.search(r"^([A-Z][^A-Z]*?\.\s)", " ".join(doc).strip())
if m:
summary = m.group(1).strip()
elif doc:
summary = doc[0].strip()
else:
summary = ''
items.append((display_name, sig, summary, real_name))
return items
def get_items(self, names):
"""Try to import the given names, and return a list of
``[(name, signature, summary_string, real_name), ...]``.
"""
prefixes = autosummary.get_import_prefixes_from_env(self.env)
items = []
max_item_chars = 50
for name in names:
display_name = name
if name.startswith("~"):
name = name[1:]
display_name = name.split(".")[-1]
try:
with autosummary.mock(self.config.autosummary_mock_imports):
real_name, obj, parent, modname = autosummary.import_by_name(
name, prefixes=prefixes)
except ImportError:
autosummary.logger.warning(
__("autosummary: failed to import %s"),
name,
location=self.get_source_info(),
)
continue
# initialize for each documenter
self.bridge.result = autosummary.StringList()
full_name = real_name
if not isinstance(obj, autosummary.ModuleType):
# give explicitly separated module name, so that members
# of inner classes can be documented
full_name = modname + "::" + full_name[len(modname) + 1:]
# NB. using full_name here is important, since Documenters
# handle module prefixes slightly differently
documenter = self.create_documenter(self.env.app, obj, parent,
full_name)
if not documenter.parse_name():
autosummary.logger.warning(
__("failed to parse name %s"),
real_name,
location=self.get_source_info(),
)
items.append((display_name, "", "", real_name))
continue
if not documenter.import_object():
autosummary.logger.warning(
__("failed to import object %s"),
real_name,
location=self.get_source_info(),
)
items.append((display_name, "", "", real_name))
continue
if documenter.options.members and not documenter.check_module():
continue
# try to also get a source code analyzer for attribute docs
try:
documenter.analyzer = autosummary.ModuleAnalyzer.for_module(
documenter.get_real_modname())
# parse right now, to get PycodeErrors on parsing (results will
# be cached anyway)
documenter.analyzer.find_attr_docs()
except autosummary.PycodeError as err:
autosummary.logger.debug(
"[autodoc] module analyzer failed: %s", err)
# no source file -- e.g. for builtin and C modules
documenter.analyzer = None
# -- Grab the signature
try:
sig = documenter.format_signature(show_annotation=False)
except TypeError:
# the documenter does not support ``show_annotation`` option
sig = documenter.format_signature()
if not sig:
sig = ""
else:
max_chars = max(10, max_item_chars - len(display_name))
sig = autosummary.mangle_signature(sig, max_chars=max_chars)
# -- Grab the summary
documenter.add_content(None)
summary = autosummary.extract_summary(self.bridge.result.data[:],
self.state.document)
items.append((display_name, sig, summary, real_name))
return items
def get_items(self, names):
"""Try to import the given names, and return a list of
``[(name, signature, summary_string, real_name), ...]``.
"""
from sphinx.ext.autosummary import (get_import_prefixes_from_env,
import_by_name, get_documenter, mangle_signature)
env = self.state.document.settings.env
prefixes = get_import_prefixes_from_env(env)
items = []
max_item_chars = 50
for name in names:
display_name = name
if name.startswith('~'):
name = name[1:]
display_name = name.split('.')[-1]
try:
import_by_name_values = import_by_name(name, prefixes=prefixes)
except ImportError:
self.warn('[astropyautosummary] failed to import %s' % name)
items.append((name, '', '', name))
continue
# to accommodate Sphinx v1.2.2 and v1.2.3
if len(import_by_name_values) == 3:
real_name, obj, parent = import_by_name_values
elif len(import_by_name_values) == 4:
real_name, obj, parent, module_name = import_by_name_values
# NB. using real_name here is important, since Documenters
# handle module prefixes slightly differently
documenter = get_documenter(obj, parent)(self, real_name)
if not documenter.parse_name():
self.warn('[astropyautosummary] failed to parse name %s' % real_name)
items.append((display_name, '', '', real_name))
continue
if not documenter.import_object():
self.warn('[astropyautosummary] failed to import object %s' % real_name)
items.append((display_name, '', '', real_name))
continue
# -- Grab the signature
sig = documenter.format_signature()
if not sig:
sig = ''
else:
max_chars = max(10, max_item_chars - len(display_name))
sig = mangle_signature(sig, max_chars=max_chars)
sig = sig.replace('*', r'\*')
# -- Grab the summary
doc = list(documenter.process_doc(documenter.get_doc()))
while doc and not doc[0].strip():
doc.pop(0)
m = _itemsummrex.search(" ".join(doc).strip())
if m:
summary = m.group(1).strip()
elif doc:
summary = doc[0].strip()
else:
summary = ''
items.append((display_name, sig, summary, real_name))
return items
def get_items(self,
names: List[str]) -> List[Tuple[str, str, str, str, str]]:
"""Try to import the given names, and return a list of
``[(name, signature, summary_string, real_name, env_summary), ...]``.
"""
prefixes = get_import_prefixes_from_env(self.env)
items = [] # type: List[Tuple[str, str, str, str, str]]
max_item_chars = 50
for name in names:
display_name = name
if name.startswith('~'):
name = name[1:]
display_name = name.split('.')[-1]
try:
with mock(self.config.autosummary_mock_imports):
real_name, obj, parent, modname = import_by_name(
name, prefixes=prefixes)
except ImportError:
logger.warning(__('failed to import %s'), name)
items.append((name, '', '', name, ''))
continue
self.bridge.result = StringList() # initialize for each documenter
full_name = real_name
if not isinstance(obj, ModuleType):
# give explicitly separated module name, so that members
# of inner classes can be documented
full_name = modname + '::' + full_name[len(modname) + 1:]
# NB. using full_name here is important, since Documenters
# handle module prefixes slightly differently
doccls = get_documenter(self.env.app, obj, parent)
documenter = doccls(self.bridge, full_name)
if not documenter.parse_name():
logger.warning(__('failed to parse name %s'), real_name)
items.append((display_name, '', '', real_name, ''))
continue
if not documenter.import_object():
logger.warning(__('failed to import object %s'), real_name)
items.append((display_name, '', '', real_name, ''))
continue
if documenter.options.members and not documenter.check_module():
continue
# try to also get a source code analyzer for attribute docs
try:
documenter.analyzer = ModuleAnalyzer.for_module(
documenter.get_real_modname())
# parse right now, to get PycodeErrors on parsing (results will
# be cached anyway)
documenter.analyzer.find_attr_docs()
except PycodeError as err:
logger.debug('[autodoc] module analyzer failed: %s', err)
# no source file -- e.g. for builtin and C modules
documenter.analyzer = None
# -- Grab the signature
try:
sig = documenter.format_signature(show_annotation=False)
except TypeError:
# the documenter does not support ``show_annotation`` option
sig = documenter.format_signature()
if not sig:
sig = ''
else:
max_chars = max(10, max_item_chars - len(display_name))
sig = mangle_signature(sig, max_chars=max_chars)
# -- Grab the summary
documenter.add_content(None)
summary = extract_summary(self.bridge.result.data[:],
self.state.document)
env_sum = self.extract_env_summary(self.bridge.result.data[:])
items.append((display_name, sig, summary, real_name, env_sum))
return items