def test_extract_summary(capsys): from sphinx.util.docutils import new_document from mock import Mock settings = Mock(language_code='', id_prefix='', auto_id_prefix='', pep_reference=False, rfc_reference=False) document = new_document('', settings) # normal case doc = [ '', 'This is a first sentence. And second one.', '', 'Second block is here' ] assert extract_summary(doc, document) == 'This is a first sentence.' # inliner case doc = [ 'This sentence contains *emphasis text having dots.*,', 'it does not break sentence.' ] assert extract_summary(doc, document) == ' '.join(doc) # abbreviations doc = ['Blabla, i.e. bla.'] assert extract_summary(doc, document) == 'Blabla, i.e.' _, err = capsys.readouterr() assert err == ''
def test_extract_summary(capsys): from sphinx.util.docutils import new_document from mock import Mock settings = Mock(language_code='', id_prefix='', auto_id_prefix='', pep_reference=False, rfc_reference=False) document = new_document('', settings) # normal case doc = ['', 'This is a first sentence. And second one.', '', 'Second block is here'] assert extract_summary(doc, document) == 'This is a first sentence.' # inliner case doc = ['This sentence contains *emphasis text having dots.*,', 'it does not break sentence.'] assert extract_summary(doc, document) == ' '.join(doc) # abbreviations doc = ['Blabla, i.e. bla.'] assert extract_summary(doc, document) == 'Blabla, i.e.' _, err = capsys.readouterr() assert err == ''
def get_items(self, names: List[str]) -> List[Tuple[str, str, str, str]]: items = [] # type: List[Tuple[str, str, str, str]] for display_name, sig, summary, real_name in super().get_items(names): if summary == 'Initialize self.': continue real_name, obj, parent, modname = import_by_name(real_name) del parent del modname if summary == 'Overloaded function.': for part_sig, part in _parse_overloaded_function_docstring( obj.__doc__): max_item_chars = 50 max_chars = max(10, max_item_chars - len(display_name)) mangled_sig = mangle_signature(part_sig, max_chars=max_chars) part_summary = extract_summary(part.splitlines(), self.state.document) items.append( (display_name, mangled_sig, part_summary, real_name)) else: if isinstance(obj, property): retann = _get_attribute_type(obj) if retann is not None: sig = ': ' + retann items.append((display_name, sig, summary, real_name)) return items
def extract_summary(self, descr): """Wrapper around autosummary extract_summary that is easier to use. It seems like colons need escaping for some reason. """ colon_esc = "esccolon\\\xafhoa:" # extract_summary seems to have trouble if there are Sphinx # directives in descr descr, _, _ = descr.partition("\n..") return extract_summary([descr.replace(":", colon_esc)], self.state.document).replace( colon_esc, ":")
def test_extract_summary(capsys): settings = Mock(language_code='en', id_prefix='', auto_id_prefix='', pep_reference=False, rfc_reference=False) document = new_document('', settings) # normal case doc = [ '', 'This is a first sentence. And second one.', '', 'Second block is here' ] assert extract_summary(doc, document) == 'This is a first sentence.' # inliner case doc = [ 'This sentence contains *emphasis text having dots.*,', 'it does not break sentence.' ] assert extract_summary(doc, document) == ' '.join(doc) # abbreviations doc = ['Blabla, i.e. bla.'] assert extract_summary(doc, document) == ' '.join(doc) doc = ['Blabla, et al. bla.'] assert extract_summary(doc, document) == ' '.join(doc) # literal doc = ['blah blah::'] assert extract_summary(doc, document) == 'blah blah.' # heading doc = ['blah blah', '========='] assert extract_summary(doc, document) == 'blah blah' doc = ['=========', 'blah blah', '========='] assert extract_summary(doc, document) == 'blah blah' # hyperlink target doc = [ 'Do `this <https://www.sphinx-doc.org/>`_ and that. ' 'blah blah blah.' ] assert (extract_summary( doc, document) == 'Do `this <https://www.sphinx-doc.org/>`_ and that.') _, err = capsys.readouterr() assert err == ''
def _extract_summary(cls, documenter): lines = normalize(documenter.client.__doc__ or "").splitlines() if not lines: return settings = mock.Mock( auto_id_prefix="", id_prefix="", language_code="", pep_reference=False, rfc_reference=False, ) document = new_document("", settings) summary = extract_summary(lines, document) return "\n".join(textwrap.wrap(summary, 79))
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: 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