diff --git a/documenteer/conf/pipelines.py b/documenteer/conf/pipelines.py index 48ecb20..db6b3fc 100644 --- a/documenteer/conf/pipelines.py +++ b/documenteer/conf/pipelines.py @@ -14,6 +14,8 @@ This configuration is broken down into these sections: Intersphinx configuration #HTML HTML builder and theme configuration +#BREATHE + breathe and exhale configuration for C++ reference #AUTOMODAPI automodapi and autodoc configuration #GRAPHVIZ @@ -69,6 +71,9 @@ __all__ = ( 'html_show_copyright', 'html_file_suffix', 'html_search_language', + # BREATHE + 'breathe_projects', + 'breathe_default_project', # AUTOMODAPI 'numpydoc_show_class_members', 'autosummary_generate', @@ -290,6 +295,13 @@ html_file_suffix = '.html' # Language to be used for generating the HTML full-text search index. html_search_language = 'en' +# ============================================================================ +# #BREATHE breathe and exhale configuration for C++ reference +# ============================================================================ +breathe_projects = { + "LSST": "_doxygen/xml" +} +breathe_default_project = "LSST" # ============================================================================ # #AUTOMODAPI automodapi and autodoc configuration diff --git a/documenteer/stackdocs/build.py b/documenteer/stackdocs/build.py index 3be5aa8..dac1e96 100644 --- a/documenteer/stackdocs/build.py +++ b/documenteer/stackdocs/build.py @@ -12,7 +12,8 @@ from .pkgdiscovery import ( discover_setup_packages, find_table_file, list_packages_in_eups_table, find_package_docs, NoPackageDocs, Package) from .doxygen import ( - DoxygenConfiguration, preprocess_package_doxygen_conf, run_doxygen) + DoxygenConfiguration, preprocess_package_doxygen_conf, run_doxygen, + run_breathe_apidoc) from ..sphinxrunner import run_sphinx @@ -186,8 +187,19 @@ def build_stack_docs( doxygen_conf.xml_output = doxygen_xml_dir + # Trim what's included from afw because not all of it is parseable. + afw_inc_path = packages['afw'].root_dir / 'include' / 'lsst' / 'afw' + doxygen_conf.excludes.extend([ + afw_inc_path / 'geom' / 'SpanSet.h', + afw_inc_path / 'geom' / 'SpanSetFunctorGetters.h', + ]) + if enable_doxygen: run_doxygen(conf=doxygen_conf, root_dir=doxygen_build_dir) + run_breathe_apidoc( + xml_dir=doxygen_xml_dir, + project='LSST', + output_dir=root_project_dir / 'cpp-api') else: # Write the doxygen configuration for debugging doxygen_conf_path = doxygen_build_dir / 'doxygen.conf' diff --git a/documenteer/stackdocs/doxygen.py b/documenteer/stackdocs/doxygen.py index 22ece70..d534fbc 100644 --- a/documenteer/stackdocs/doxygen.py +++ b/documenteer/stackdocs/doxygen.py @@ -2,7 +2,8 @@ """ __all__ = ( - 'DoxygenConfiguration', 'preprocess_package_doxygen_conf', 'run_doxygen') + 'DoxygenConfiguration', 'preprocess_package_doxygen_conf', 'run_doxygen', + 'run_breathe_apidoc') from copy import deepcopy import csv @@ -533,3 +534,37 @@ def run_doxygen(*, conf: DoxygenConfiguration, root_dir: Path) -> int: result = subprocess.run(['doxygen', str(conf_path)]) return result.returncode + + +def run_breathe_apidoc( + *, xml_dir: Path, project: str, output_dir: Path) -> int: + """Run breathe-apidoc to generate reStructuredText stubs for the C++ + API reference. + + Parameters + ---------- + xml_dir + Directory containing the ``index.xml`` file generated by Doxygen. + project + Name of the Breathe project (corresponds to ``breathe_projects`` in + the Sphinx configuration. + output_dir + Directory where reStructuredText files are written. + + Returns + ------- + status + The shell status code returned by the ``breathe-apidoc`` executable. + """ + # breathe-apidoc _doxygen/xml -o cpp-api -p LSST + result = subprocess.run([ + 'breathe-apidoc', + str(xml_dir), + '-o', + str(output_dir), + '-p', + 'LSST', + '-f', + '-g', + 'class,interface,struct,union,file,namespace,group']) + return result.returncode