Automatic C++ doc generation (#3950)

Co-authored-by: Paul Romano <paul.k.romano@gmail.com>

docs/source/capi/index.rst

@@ -46,43 +46,20 @@ Type Definitions
 Functions
 ---------
 
-.. c:function:: int openmc_calculate_volumes()
+..
+   Once documentation is complete in capi.h, use:
+   .. doxygenfile:: capi.h
+   to populate this documentation without using
+   .. doxygenfunction::
+   for every function.
 
-   Run a stochastic volume calculation
+.. doxygenfunction:: openmc_calculate_volumes
 
-   :return: Return status (negative if an error occurred)
-   :rtype: int
+.. doxygenfunction:: openmc_cell_get_fill
 
-.. c:function:: int openmc_cell_get_fill(int32_t index, int* type, int32_t** indices, int32_t* n)
+.. doxygenfunction:: openmc_cell_get_id
 
-   Get the fill for a cell
-
-   :param int32_t index: Index in the cells array
-   :param int* type: Type of the fill
-   :param int32_t** indices: Array of material indices for cell
-   :param int32_t* n: Length of indices array
-   :return: Return status (negative if an error occurred)
-   :rtype: int
-
-.. c:function:: int openmc_cell_get_id(int32_t index, int32_t* id)
-
-   Get the ID of a cell
-
-   :param int32_t index: Index in the cells array
-   :param int32_t* id: ID of the cell
-   :return: Return status (negative if an error occurred)
-   :rtype: int
-
-.. c:function:: int openmc_cell_get_temperature(int32_t index, const int32_t* instance, double* T)
-
-   Get the temperature of a cell
-
-   :param int32_t index: Index in the cells array
-   :param int32_t* instance: Which instance of the cell. If a null pointer is passed, the temperature
-                             of the first instance is returned.
-   :param double* T: temperature of the cell
-   :return: Return status (negative if an error occurred)
-   :rtype: int
+.. doxygenfunction:: openmc_cell_get_temperature
 
 .. c:function:: int openmc_cell_get_density(int32_t index, const int32_t* instance, double* density)
 

docs/source/conf.py

@@ -11,7 +11,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import os
+from pathlib import Path
+import subprocess
+import sys
 
 # Determine if we're on Read the Docs server
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
@@ -37,6 +40,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    'breathe',
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.autosummary',
@@ -47,6 +51,8 @@ extensions = [
 ]
 if not on_rtd:
     extensions.append('sphinxcontrib.rsvgconverter')
+    doxygen_dir = Path(__file__).parents[1] / 'doxygen'
+    subprocess.run(['doxygen'], cwd=doxygen_dir, check=True)
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -117,6 +123,11 @@ pygments_style = 'tango'
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+# -- Options breathe + doxygen -------------------------------------------------
+
+breathe_projects = {"OpenMC": "../doxygen/xml"}
+breathe_default_project = "OpenMC"
+breathe_domain_by_file_pattern = {"*capi.h": "c"}
 
 # -- Options for HTML output ---------------------------------------------------
 

docs/source/devguide/docbuild.rst

@@ -14,6 +14,11 @@ Python API. That is, from the root directory of the OpenMC repository:
 
     python -m pip install ".[docs]"
 
+The OpenMC documentation also uses Doxygen to automatically generate its
+C/C++ API documentation directly from the docstrings available in the source
+code. You will need to have a working installation of Doxygen to generate the
+documentation locally.
+
 -----------------------------------
 Building Documentation as a Webpage
 -----------------------------------

docs/source/io_formats/geometry.rst

@@ -425,13 +425,13 @@ Each ``<dagmc_universe>`` element can have the following attributes or sub-eleme
       material) assignment. Required.
 
     :temperature:
-      Temperature(s) in [K] to assign to the cell. Must be ≥ 0. Multiple
-      space-separated values may be given.
+      Temperature(s) in [K] to assign to the cell. Must be greater than or equal
+      to 0. Multiple space-separated values may be given.
 
       *Default*: None
 
     :density:
-      Density in [g/cm³] to assign to the cell. Must be > 0. Requires a non-void
+      Density in [g/cm³] to assign to the cell. Must be greater than 0. Requires a non-void
       material fill. Multiple space-separated values may be given.
 
       *Default*: None