def remove_linebreaks_in_signature(lines):
alllines = '\n'.join(lines)
alllines = alllines.lstrip()
bits = alllines.split('->')
if len(bits) == 1:
return 0
after = '->'.join(bits[1:])
after_lines = after.split('\n')
ending = None
remainder = []
for line in after_lines:
if line and ending is None:
ending = line
elif ending is not None:
remainder.append(line)
first_line = ' '.join(
[a.strip()
for a in bits[0].split('\n') if a.strip()]) + ' -> ' + ending.strip()
match = py_ext_sig_re.match(first_line)
# If it is a signature, make the change to lines.
if match:
new_lines = [first_line] + remainder
lines[:] = new_lines
return len(bits[0].split('\n'))
else:
return 0
def _find_signature(self, encoding=None):
docstrings = MatlabDocumenter.get_doc(self, encoding)
if len(docstrings) != 1:
return
doclines = docstrings[0]
setattr(self, '__new_doclines', doclines)
if not doclines:
return
# match first line of docstring against signature RE
match = mat_ext_sig_re.match(doclines[0])
if not match:
return
exmod, path, base, args, retann = match.groups()
# the base name must match ours
if not self.objpath or base != self.objpath[-1]:
return
# re-prepare docstring to ignore indentation after signature
docstrings = MatlabDocumenter.get_doc(self, encoding, 2)
doclines = docstrings[0]
# ok, now jump over remaining empty lines and set the remaining
# lines as the new doclines
i = 1
while i < len(doclines) and not doclines[i].strip():
i += 1
setattr(self, '__new_doclines', doclines[i:])
return args, retann
def fix_signature(app, what, name, obj, options, signature, return_annotation):
"""
SWIG produces signature at the top of docstrings of the form
'blah(int arg1, float arg2) -> return_type'
and if the string is long it breaks it over multiple lines.
Sphinx gets confused if it is broken over multiple lines.
fix_signature and remove_lines get around this problem.
"""
if return_annotation is not None:
return
if hasattr(obj, '__doc__'):
docs = obj.__doc__
else:
docs = None
if not docs:
return None
doclines = docs.split('\n')
del_lines = remove_linebreaks_in_signature(doclines)
# match first line of docstring against signature RE
match = py_ext_sig_re.match(doclines[0])
if not match:
return None
exmod, path, base, args, retann = match.groups()
# ok, now jump over remaining empty lines and set the remaining
# lines as the new doclines
i = 1
while i < len(doclines) and not doclines[i].strip():
i += 1
lines_to_delete[name] = i - 1 + del_lines
# format args
signature = "({0})".format(args)
return signature, retann
def fix_signature(app, what, name, obj, options, signature, return_annotation):
"""
SWIG produces signature at the top of docstrings of the form
'blah(int arg1, float arg2) -> return_type'
and if the string is long it breaks it over multiple lines.
Sphinx gets confused if it is broken over multiple lines.
fix_signature and remove_lines get around this problem.
"""
if return_annotation is not None:
return
if hasattr(obj, '__doc__'):
docs = obj.__doc__
else:
docs = None
if not docs:
return None
doclines = docs.split('\n')
del_lines = remove_linebreaks_in_signature(doclines)
# match first line of docstring against signature RE
match = py_ext_sig_re.match(doclines[0])
if not match:
return None
exmod, path, base, args, retann = match.groups()
# ok, now jump over remaining empty lines and set the remaining
# lines as the new doclines
i = 1
while i < len(doclines) and not doclines[i].strip():
i += 1
lines_to_delete[name] = i - 1 + del_lines
# format args
signature = "({0})".format(args)
return signature, retann
def _find_signature(self, encoding=None):
docstrings = MatlabDocumenter.get_doc(self, encoding)
if len(docstrings) != 1:
return
doclines = docstrings[0]
setattr(self, '__new_doclines', doclines)
if not doclines:
return
# match first line of docstring against signature RE
match = mat_ext_sig_re.match(doclines[0])
if not match:
return
exmod, path, base, args, retann = match.groups()
# the base name must match ours
if not self.objpath or base != self.objpath[-1]:
return
# re-prepare docstring to ignore indentation after signature
docstrings = MatlabDocumenter.get_doc(self, encoding, 2)
doclines = docstrings[0]
# ok, now jump over remaining empty lines and set the remaining
# lines as the new doclines
i = 1
while i < len(doclines) and not doclines[i].strip():
i += 1
setattr(self, '__new_doclines', doclines[i:])
return args, retann
def process_signature(app, what, name, obj, options, signature,
return_annotation):
"""
Replace function signature with those specified in the docstring.
"""
if hasattr(obj, '__doc__') and obj.__doc__ is not None:
lines = prepare_docstring(obj.__doc__)
siglines = []
for line in lines:
if py_ext_sig_re.match(line) is not None:
siglines.append(line)
else:
break
if len(siglines):
siglines[0] = siglines[0][siglines[0].index('('):]
return ('\n'.join(siglines), None)
return (signature, return_annotation)
def process_signature(app, what, name, obj,
options, signature, return_annotation):
"""
Replace function signature with those specified in the docstring.
"""
if hasattr(obj, '__doc__') and obj.__doc__ is not None:
lines = prepare_docstring(obj.__doc__)
siglines = []
for line in lines:
if py_ext_sig_re.match(line) is not None:
siglines.append(line)
else:
break
if len(siglines):
siglines[0] = siglines[0][siglines[0].index('('):]
return ('\n'.join(siglines), None)
return (signature, return_annotation)
def parse_name(self):
"""Determine what module to import and what attribute to document.
Returns True and sets *self.modname*, *self.objpath*, *self.fullname*,
*self.args* and *self.retann* if parsing and resolving was successful.
"""
# first, parse the definition -- auto directives for classes and
# functions can contain a signature which is then used instead of
# an autogenerated one
try:
explicit_modname, path, base, args, retann = \
mat_ext_sig_re.match(self.name).groups()
except AttributeError:
self.directive.warn('invalid signature for auto%s (%r)' %
(self.objtype, self.name))
return False
# support explicit module and class name separation via ::
if explicit_modname is not None:
modname = explicit_modname[:-2]
parents = path and path.rstrip('.').split('.') or []
else:
modname = None
parents = []
self.modname, self.objpath = self.resolve_name(modname, parents, path,
base)
if not self.modname:
return False
self.args = args
self.retann = retann
self.fullname = (self.modname or '') + \
(self.objpath and '.' + '.'.join(self.objpath) or '')
return True
def remove_linebreaks_in_signature(lines):
alllines = '\n'.join(lines)
alllines = alllines.lstrip()
bits = alllines.split('->')
if len(bits) == 1:
return 0
after = '->'.join(bits[1:])
after_lines = after.split('\n')
ending = None
remainder = []
for line in after_lines:
if line and ending is None:
ending = line
elif ending is not None:
remainder.append(line)
first_line = ' '.join([a.strip() for a in bits[0].split('\n') if a.strip()]) + ' -> ' + ending.strip()
match = py_ext_sig_re.match(first_line)
# If it is a signature, make the change to lines.
if match:
new_lines = [first_line] + remainder
lines[:] = new_lines
return len(bits[0].split('\n'))
else:
return 0
def parse_name(self):
"""Determine what module to import and what attribute to document.
Returns True and sets *self.modname*, *self.objpath*, *self.fullname*,
*self.args* and *self.retann* if parsing and resolving was successful.
"""
# first, parse the definition -- auto directives for classes and
# functions can contain a signature which is then used instead of
# an autogenerated one
try:
explicit_modname, path, base, args, retann = \
mat_ext_sig_re.match(self.name).groups()
except AttributeError:
self.directive.warn('invalid signature for auto%s (%r)' %
(self.objtype, self.name))
return False
# support explicit module and class name separation via ::
if explicit_modname is not None:
modname = explicit_modname[:-2]
parents = path and path.rstrip('.').split('.') or []
else:
modname = None
parents = []
self.modname, self.objpath = \
self.resolve_name(modname, parents, path, base)
if not self.modname:
return False
self.args = args
self.retann = retann
self.fullname = (self.modname or '') + \
(self.objpath and '.' + '.'.join(self.objpath) or '')
return True
def process_docstring(app, what, name, obj, options, lines):
"""
Remove leading function signatures from docstring.
"""
while len(lines) and py_ext_sig_re.match(lines[0]) is not None:
del lines[0]
def process_docstring(app, what, name, obj, options, lines):
"""
Remove leading function signatures from docstring.
"""
while len(lines) and py_ext_sig_re.match(lines[0]) is not None:
del lines[0]
