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: 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