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)