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
