diff --git a/.gitignore b/.gitignore index dd8dfb14a96..32ef7919ab4 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,7 @@ examples/**/*.xml # Documentation builds docs/build +docs/doxygen/xml docs/source/_images/*.pdf docs/source/_images/*.aux docs/source/pythonapi/generated/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 61301bdb499..7594ed5f2b6 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -7,6 +7,8 @@ build: jobs: post_checkout: - git fetch --unshallow || true + - cd docs/doxygen && doxygen && cd - + sphinx: configuration: docs/source/conf.py diff --git a/docs/Makefile b/docs/Makefile index a93338df31f..e320432a20b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -45,6 +45,7 @@ help: clean: -rm -rf $(BUILDDIR)/* -rm -rf source/pythonapi/generated/ + -rm -rf doxygen/xml html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile new file mode 100644 index 00000000000..186fd8a011e --- /dev/null +++ b/docs/doxygen/Doxyfile @@ -0,0 +1,14 @@ +# Doxyfile 1.9.1 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. + +# Difference with default Doxyfile 1.9.1 +PROJECT_NAME = OpenMC +QUIET = YES +WARN_IF_UNDOCUMENTED = NO +INPUT = ../../include/openmc/ +RECURSIVE = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES diff --git a/docs/source/capi/index.rst b/docs/source/capi/index.rst index 1777e795ad7..e924aa6e2a9 100644 --- a/docs/source/capi/index.rst +++ b/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 - -.. c:function:: int openmc_cell_get_fill(int32_t index, int* type, int32_t** indices, int32_t* n) - - 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) +.. doxygenfunction:: openmc_cell_get_fill - Get the ID of a cell +.. doxygenfunction:: openmc_cell_get_id - :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) diff --git a/docs/source/conf.py b/docs/source/conf.py index 3a2e7fb93b1..699b75d340e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,7 +11,7 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import sys, os, subprocess # Determine if we're on Read the Docs server on_rtd = os.environ.get('READTHEDOCS', None) == 'True' @@ -37,6 +37,7 @@ # 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 +48,7 @@ ] if not on_rtd: extensions.append('sphinxcontrib.rsvgconverter') + subprocess.run(['doxygen'], cwd='../doxygen') # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -117,6 +119,10 @@ # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] +# -- Options breathe + doxygen ------------------------------------------------- + +breathe_projects = {"OpenMC": "../doxygen/xml"} +breathe_default_project = "OpenMC" # -- Options for HTML output --------------------------------------------------- diff --git a/include/openmc/capi.h b/include/openmc/capi.h index 911654d318f..f8b13ae5826 100644 --- a/include/openmc/capi.h +++ b/include/openmc/capi.h @@ -9,14 +9,41 @@ extern "C" { #endif +//! Run a stochastic volume calculation +// +//! \return Status (negative if an error occurred) int openmc_calculate_volumes(); + int openmc_cell_filter_get_bins( int32_t index, const int32_t** cells, int32_t* n); + +//! Get the fill for a cell +// +//! \param index Index in the cells array +//! \param type Type of the fill +//! \param indices Array of material indices for cell +//! \param n Length of indices array +//! \return Status (negative if an error occurred) int openmc_cell_get_fill( int32_t index, int* type, int32_t** indices, int32_t* n); + +//! Get the ID of a cell +// +//! \param index Index in the cells array +//! \param id ID of the cell +//! \return Status (negative if an error occurred) int openmc_cell_get_id(int32_t index, int32_t* id); + +//! Get the temperature of a cell +// +//! \param index Index in the cells array +//! \param instance Which instance of the cell. If a null pointer is +//! passed, the temperature of the first instance is returned. +//! \param T temperature of the cell +//!\return Status (negative if an error occurred) int openmc_cell_get_temperature( int32_t index, const int32_t* instance, double* T); + int openmc_cell_get_density( int32_t index, const int32_t* instance, double* rho); int openmc_cell_get_translation(int32_t index, double xyz[]); diff --git a/pyproject.toml b/pyproject.toml index 098487c06ed..c769fb7d760 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,6 +40,7 @@ dependencies = [ [project.optional-dependencies] depletion-mpi = ["mpi4py"] docs = [ + "breathe", "sphinx", "sphinxcontrib-katex", "sphinx-numfig",