def build_docstrings(headers, component_name, doxygen_config_filename,
siconos_swig_path):
"""Create docstrings (doxy2swig) in swig files from xml (doxygen) generated
from headers.
Parameters
----------
headers : list (cmake like)
headers files to parse
component_name : string
component (numerics, kernel, ...) of interest
doxygen_config_filename : string
name (full path) of the doxygen configuration file
siconos_swig_path : string
path to swig outputs in binary dir (i.e. wrap)
Note
----
* all swig files will be genereted into
siconos_swig_path/tmp_component_name directory
and concatenated into component_name-docstrings.i
that will be the file really used by swig.
* This function is supposed to be called by a target generated
with cmake (make <component>_docstrings)
"""
doxyconf = common.parse_doxygen_config(doxygen_config_filename)
case_sense_names = doxyconf['CASE_SENSE_NAMES'].find('YES') > -1
xml_path = Path(doxyconf['OUTPUT_DIRECTORY'].lstrip(),
doxyconf['XML_OUTPUT'].lstrip())
headers = bt.parse_cmake_list(headers)
swig_working_dir = Path(siconos_swig_path, 'tmp_' + component_name)
if not swig_working_dir.exists():
os.makedirs(swig_working_dir)
docstrings_features = {}
all_index = {}
for hfile in headers:
xml2swig(hfile, xml_path, swig_working_dir, case_sense_names,
docstrings_features, all_index)
# Save features info in a pickle file
pickle_filename = Path(siconos_swig_path, component_name + '.pickle')
with open(pickle_filename, 'wb') as currentfile:
pickle.dump(docstrings_features, currentfile)
# Save classes, files names and descriptions (for toc)
pickle_filename = Path(siconos_swig_path, component_name + '_index.pickle')
with open(pickle_filename, 'wb') as currentfile:
pickle.dump(all_index, currentfile)
# Creates <component>-docstrings.i
outputfile = Path(siconos_swig_path, component_name + '-docstrings.i')
swigfiles = [f for f in swig_working_dir.glob('*.i')]
with open(outputfile, 'w', encoding='utf8') as outfile:
for fname in swigfiles:
with open(fname, encoding='utf8') as infile:
for line in infile:
outfile.write(line)
msg = 'Generates (python) file ' + outputfile.name
msg += ' for doctrings in swig.'
print(msg)
def create_breathe_files(headers, srcdir, component_name, sphinx_directory,
doxygen_config_filename):
"""Create rst files for sphinx from xml (doxygen) outputs generated
from headers.
Parameters
----------
headers : list (cmake like)
headers files to parse
srcdir : string
absolute path to c/c++ sources (CMAKE_SOURCE_DIR)
component_name : string
component (numerics, kernel, ...) of interest
sphinx_directory : string
root directory for sphinx rst files
doxygen_config_filename : string
name (full path) of the doxygen configuration file
Notes:
* for each header, rst files (class, struct, file and source codes)
will be generated
* three other 'main' rst files will be produced :
* breathe_api.rst, with the toctree for all classes and structs
* files_list.rst, with the toctree for all files documentation
* sources_list.rst with the toctree for all program listings
This function is supposed to be called by a target created with cmake
(make <component>-xml2rst)
"""
# Get all headers for the current component, as a list.
headers = bt.parse_cmake_list(headers)
rst_files = []
# Parse doxygen config (specific to the current component)
doxyconf = common.parse_doxygen_config(doxygen_config_filename)
xmlconf = {}
# Output path for cpp api documentation
sphinx_directory = Path(sphinx_directory, 'reference', 'cpp',
component_name)
if not sphinx_directory.exists():
os.makedirs(sphinx_directory)
# Check if doxygen doc is case-sensitive
xmlconf['CASE_SENSE_NAMES'] = doxyconf['CASE_SENSE_NAMES'].find('YES') > -1
# Get xml files path
xmlconf['XML_OUTPUT'] = Path(doxyconf['OUTPUT_DIRECTORY'].lstrip(),
doxyconf['XML_OUTPUT'].lstrip())
all_index = {}
# -- Create rst for classes, structs and files found in xml directory --
for hfile in headers:
xml2rst(Path(hfile), srcdir, component_name, sphinx_directory, xmlconf,
all_index)
# -- Create rst files to collect list of classes and files
# (i.e. files created above) --
class_and_struct_files = [f for f in sphinx_directory.glob('class*.rst')]
class_and_struct_files += [f for f in sphinx_directory.glob('struct*.rst')]
class_and_struct_files.sort()
pgm_files = [f for f in sphinx_directory.glob('pgm_*.rst')]
pgm_files.sort()
rst_files = [f for f in sphinx_directory.glob('file_*.rst')]
rst_files.sort()
all_files = class_and_struct_files + rst_files
all_files.sort()
# -- Name of the main rst files for the current component --
# usually : docs/sphinx/reference/cpp/component_name/autodoc_all.rst
outputname = Path(sphinx_directory, 'autodoc_all.rst')
autodoc_collect(outputname, all_files, all_index, component_name)
# Classes and structs
outputname = Path(sphinx_directory, 'autodoc_classes.rst')
autodoc_collect(outputname,
class_and_struct_files,
all_index,
component_name,
subtitle='Classes and structs')
# Files doc
outputname = Path(sphinx_directory, 'autodoc_files.rst')
autodoc_collect(outputname,
rst_files,
all_index,
component_name,
subtitle='Files documentation')
# Programs listings
autodoc_collect_pgm(pgm_files, component_name, sphinx_directory)
def create_breathe_files(headers, srcdir, component_name,
sphinx_directory, doxygen_config_filename):
"""Create rst files for sphinx from xml (doxygen) outputs generated
from headers.
Parameters
----------
headers : list (cmake like)
headers files to parse
srcdir : string
absolute path to c/c++ sources (CMAKE_SOURCE_DIR)
component_name : string
component (numerics, kernel, ...) of interest
sphinx_directory : string
root directory for sphinx rst files
doxygen_config_filename : string
name (full path) of the doxygen configuration file
Notes:
* for each header, rst files (class, struct, file and source codes)
will be generated
* three other 'main' rst files will be produced :
* breathe_api.rst, with the toctree for all classes and structs
* files_list.rst, with the toctree for all files documentation
* sources_list.rst with the toctree for all program listings
This function is supposed to be called by a target created with cmake
(make <component>-xml2rst)
"""
# Get all headers for the current component, as a list.
headers = bt.parse_cmake_list(headers)
rst_files = []
# Parse doxygen config (specific to the current component)
doxyconf = common.parse_doxygen_config(doxygen_config_filename)
xmlconf = {}
# Output path for cpp api documentation
sphinx_directory = Path(sphinx_directory, 'reference',
'cpp', component_name)
if not sphinx_directory.exists():
os.makedirs(sphinx_directory)
# Check if doxygen doc is case-sensitive
xmlconf['CASE_SENSE_NAMES'] = doxyconf['CASE_SENSE_NAMES'].find('YES') > -1
# Get xml files path
xmlconf['XML_OUTPUT'] = Path(doxyconf['OUTPUT_DIRECTORY'].lstrip(),
doxyconf['XML_OUTPUT'].lstrip())
all_index = {}
# -- Create rst for classes, structs and files found in xml directory --
for hfile in headers:
xml2rst(Path(hfile), srcdir, component_name, sphinx_directory,
xmlconf, all_index)
# -- Create rst files to collect list of classes and files
# (i.e. files created above) --
class_and_struct_files = [f for f in sphinx_directory.glob('class*.rst')]
class_and_struct_files += [f for f in sphinx_directory.glob('struct*.rst')]
class_and_struct_files.sort()
pgm_files = [f for f in sphinx_directory.glob('pgm_*.rst')]
pgm_files.sort()
rst_files = [f for f in sphinx_directory.glob('file_*.rst')]
rst_files.sort()
all_files = class_and_struct_files + rst_files
all_files.sort()
# -- Name of the main rst files for the current component --
# usually : docs/sphinx/reference/cpp/component_name/autodoc_all.rst
outputname = Path(sphinx_directory, 'autodoc_all.rst')
autodoc_collect(outputname, all_files, all_index, component_name)
# Classes and structs
outputname = Path(sphinx_directory, 'autodoc_classes.rst')
autodoc_collect(outputname, class_and_struct_files,
all_index, component_name, subtitle='Classes and structs')
# Files doc
outputname = Path(sphinx_directory, 'autodoc_files.rst')
autodoc_collect(outputname, rst_files, all_index, component_name,
subtitle='Files documentation')
# Programs listings
autodoc_collect_pgm(pgm_files, component_name, sphinx_directory)