def generate_api_doc(self, uri):
'''Make autodoc documentation template string for a module
Parameters
----------
uri : string
python location of module - e.g 'sphinx.builder'
Returns
-------
S : string
Contents of API doc
'''
# get the names of all classes and functions
functions, classes = self._parse_module(uri)
workflows = []
helper_functions = []
for function in functions:
try:
__import__(uri)
finst = sys.modules[uri].__dict__[function]
except TypeError:
continue
try:
workflow = finst()
except Exception:
helper_functions.append((function, finst))
continue
if isinstance(workflow, Workflow):
workflows.append((workflow,function, finst))
if not classes and not workflows and not helper_functions:
print('WARNING: Empty -',uri) # dbg
return ''
# Make a shorter version of the uri that omits the package name for
# titles
uri_short = re.sub(r'^%s\.' % self.package_name, '', uri)
#uri_short = uri
ad = '.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n'
chap_title = uri_short
ad += (chap_title+'\n'+ self.rst_section_levels[1] * len(chap_title)
+ '\n\n')
# Set the chapter title to read 'module' for all modules except for the
# main packages
#if '.' in uri:
# title = 'Module: :mod:`' + uri_short + '`'
#else:
# title = ':mod:`' + uri_short + '`'
#ad += title + '\n' + self.rst_section_levels[2] * len(title)
#ad += '\n' + 'Classes' + '\n' + \
# self.rst_section_levels[2] * 7 + '\n'
for c in classes:
__import__(uri)
print(c)
try:
with warnings.catch_warnings():
warnings.simplefilter("ignore")
classinst = sys.modules[uri].__dict__[c]
except Exception as inst:
print(inst)
continue
if not issubclass(classinst, BaseInterface):
continue
label = uri + '.' + c + ':'
ad += '\n.. _%s\n\n' % label
ad += '\n.. index:: %s\n\n' % c
ad += c + '\n' + self.rst_section_levels[2] * len(c) + '\n\n'
ad += "`Link to code <%s>`__\n\n" % get_file_url(classinst)
ad += trim(classinst.help(returnhelp=True),
self.rst_section_levels[3]) + '\n'
if workflows or helper_functions:
ad += '\n.. module:: %s\n\n' % uri
for workflow, name, finst in workflows:
label = ':func:`' + name + '`'
ad += '\n.. _%s:\n\n' % (uri + '.' + name)
ad += '\n'.join((label, self.rst_section_levels[2] * len(label)))
ad += "\n\n`Link to code <%s>`__\n\n" % get_file_url(finst)
helpstr = trim(finst.__doc__, self.rst_section_levels[3])
ad += '\n\n' + helpstr + '\n\n'
"""
# use sphinx autodoc for function signature
ad += '\n.. _%s:\n\n' % (uri + '.' + name)
ad += '.. autofunction:: %s\n\n' % name
"""
(_,fname) = tempfile.mkstemp(suffix=".dot")
workflow.write_graph(dotfilename=fname, graph2use='hierarchical')
ad += self._write_graph_section(fname, 'Graph') + '\n'
for name, finst in helper_functions:
label = ':func:`' + name + '`'
ad += '\n.. _%s:\n\n' % (uri + '.' + name)
ad += '\n'.join((label, self.rst_section_levels[2] * len(label)))
ad += "\n\n`Link to code <%s>`__\n\n" % get_file_url(finst)
helpstr = trim(finst.__doc__, self.rst_section_levels[3])
ad += '\n\n' + helpstr + '\n\n'
return ad
def generate_api_doc(self, uri):
'''Make autodoc documentation template string for a module
Parameters
----------
uri : string
python location of module - e.g 'sphinx.builder'
Returns
-------
S : string
Contents of API doc
'''
# get the names of all classes and functions
functions, classes = self._parse_module(uri)
workflows = []
helper_functions = []
for function in functions:
try:
__import__(uri)
finst = sys.modules[uri].__dict__[function]
except TypeError:
continue
try:
workflow = finst()
except Exception:
helper_functions.append((function, finst))
continue
if isinstance(workflow, Workflow):
workflows.append((workflow, function, finst))
if not classes and not workflows and not helper_functions:
print 'WARNING: Empty -', uri # dbg
return ''
# Make a shorter version of the uri that omits the package name for
# titles
uri_short = re.sub(r'^%s\.' % self.package_name, '', uri)
#uri_short = uri
ad = '.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n'
chap_title = uri_short
ad += (chap_title + '\n' +
self.rst_section_levels[1] * len(chap_title) + '\n\n')
# Set the chapter title to read 'module' for all modules except for the
# main packages
#if '.' in uri:
# title = 'Module: :mod:`' + uri_short + '`'
#else:
# title = ':mod:`' + uri_short + '`'
#ad += title + '\n' + self.rst_section_levels[2] * len(title)
#ad += '\n' + 'Classes' + '\n' + \
# self.rst_section_levels[2] * 7 + '\n'
for c in classes:
__import__(uri)
print c
try:
with warnings.catch_warnings():
warnings.simplefilter("ignore")
classinst = sys.modules[uri].__dict__[c]
except Exception as inst:
print inst
continue
if not issubclass(classinst, BaseInterface):
continue
label = uri + '.' + c + ':'
ad += '\n.. _%s\n\n' % label
ad += '\n.. index:: %s\n\n' % c
ad += c + '\n' + self.rst_section_levels[2] * len(c) + '\n\n'
ad += "`Link to code <%s>`__\n\n" % get_file_url(classinst)
ad += trim(classinst.help(returnhelp=True),
self.rst_section_levels[3]) + '\n'
if workflows or helper_functions:
ad += '\n.. module:: %s\n\n' % uri
for workflow, name, finst in workflows:
label = ':func:`' + name + '`'
ad += '\n.. _%s:\n\n' % (uri + '.' + name)
ad += '\n'.join((label, self.rst_section_levels[2] * len(label)))
ad += "\n\n`Link to code <%s>`__\n\n" % get_file_url(finst)
helpstr = trim(finst.__doc__, self.rst_section_levels[3])
ad += '\n\n' + helpstr + '\n\n'
"""
# use sphinx autodoc for function signature
ad += '\n.. _%s:\n\n' % (uri + '.' + name)
ad += '.. autofunction:: %s\n\n' % name
"""
(_, fname) = tempfile.mkstemp(suffix=".dot")
workflow.write_graph(dotfilename=fname, graph2use='hierarchical')
ad += self._write_graph_section(fname, 'Graph') + '\n'
for name, finst in helper_functions:
label = ':func:`' + name + '`'
ad += '\n.. _%s:\n\n' % (uri + '.' + name)
ad += '\n'.join((label, self.rst_section_levels[2] * len(label)))
ad += "\n\n`Link to code <%s>`__\n\n" % get_file_url(finst)
helpstr = trim(finst.__doc__, self.rst_section_levels[3])
ad += '\n\n' + helpstr + '\n\n'
return ad
