def write_python_module_toc(module_name, all_files, sphinx_directory,
swig_working_dir, component_name):
"""Write main autodoc file for current module
Some kind of table of contents from files listed in all_files.
"""
all_index_filename = Path(swig_working_dir,
component_name + '_index.pickle')
msg = f'Unable to find {all_index_filename}.'
assert all_index_filename.resolve().exists(), msg
with open(all_index_filename, 'rb') as f:
all_index = pickle.load(f)
outputname = Path(sphinx_directory, 'autodoc_all.rst')
title = module_name + '\n'
title += len(title) * '=' + '\n\n'
basename = '/reference/python/' + module_name.replace(r'.', '_')
# A few lines to illustrate module usage
header = '**Usage example** :\n\n.. code-block:: python\n\n'
importname = 's' + module_name.split('.')[-1][0]
code = 'import ' + module_name + ' as ' + importname
code += '\n \nhelp(' + importname + '.SomeClass)\n\n'
header += textwrap.indent(code, ' ')
header += '**Classes and functions**\n\n'
with open(outputname, 'wt') as out:
out.write(title)
out.write(header)
buff = Path(basename, 'autodoc_pydata').as_posix()
gen = '* :doc:`Enums and constants <' + buff + '>`\n'
for f in all_files:
name = f.stem
text = ''
if '_pyclass' in name:
realname = name.split('_pyclass')[0]
shorttitle = realname + ' (class) '
text = '* :py:class:`' + module_name + '.' + realname + '` : '
try:
text += all_index[realname] + '\n'
except:
text += ' \n'
elif '_pyfile' in name:
realname = name.split('_pyfile')[0]
shorttitle = realname + ' (functions) '
text = '* :doc:`' + shorttitle + '<'
text += Path(basename, name).as_posix() + '>` : '
if realname + '.h' in all_index:
text += all_index[realname + '.h'] + ' \n'
elif realname + '.hpp' in all_index:
text += all_index[realname + '.hpp'] + ' \n'
else:
text += ' \n'
else:
shorttitle = ''
gen += text
out.write(gen + '\n')
# It might be necessary to parse some latex from doxygen
# and convert it to sphinx ...
latex_dir = Path(swig_working_dir, 'tmp_' + component_name)
common.replace_latex(outputname, latex_dir)
def process_enums(module, module_name, features, sphinx_directory,
swig_working_dir, component_name):
"""Parse features to find enums and populate
a rst with the proper autodoc directives.
"""
# Get saved enums for the current module
outputname = Path(sphinx_directory, 'autodoc_pydata.rst')
title = module_name + ' constants (Python API)\n'
title += len(title) * '-' + '\n\n'
title += 'All the predefined global constants in ' + module_name
title += '(generated from C++ enum, global variables, ...) \n\n'
enumskeys = [k for k in features if k.find('pydata') > -1]
header = '**Usage** :\n\n.. code-block:: python\n\n'
importname = 's' + module_name.split('.')[-1][0]
code = 'import ' + module_name + ' as ' + importname
code += '\n \nprint(' + importname + '.CONSTNAME)\n\n'
header += textwrap.indent(code, ' ')
title += header
title += '\n-----\n\n**List and descriptions of constants** :\n\n'
with open(outputname, 'wt') as out:
out.write(title)
for key in enumskeys:
enums = features[key]
for ename in enums:
# Document only data available in python API
if hasattr(module, ename):
# and only data with a description
if enums[ename][1].strip():
gen = ''
gen += '.. _pydata_' + ename + ':\n\n'
gen += '.. py:data:: ' + ename + '\n\n'
if enums[ename][0]:
# Add initializer value if set
gen += ' {0} ({1})\n\n'.format(
enums[ename][1].strip(), enums[ename][0])
else:
gen += ' {0} \n\n'.format(
enums[ename][1].strip())
out.write(gen)
# It might be necessary to parse some
# latex from doxygen and convert it to sphinx ...
latex_dir = Path(swig_working_dir, 'tmp_' + component_name)
common.replace_latex(outputname, latex_dir)