Generated YAML Output#

Note

The generated YAML output summarizes elements of the CLib API in YAML format and serves for illustration purposes. The YAML source code generator may be used to generate diagnostic output as well as a starting point for the creation of additional generated language interfaces.

The YAML source generator generates YAML descriptions that correspond to individual CLib modules generated from specification files. Each output file contains mappings of CLib function names to implementation details of individual recipes.

Example: Using the same input as in the Generated CLib API example, the YAML source generator documents the CLib getter for molecular weights as follows:

thermo_getMolecularWeights:
  brief: Copy the vector of molecular weights into array weights.
  what: getter
  declaration: int32_t thermo_getMolecularWeights(int32_t handle, int32_t weightsLen, double* weights)
  parameters:
    handle: Handle to queried Phase object.
    weightsLen: Length of array reserved for weights.
    weights: Output array of molecular weights (kg/kmol)
  wraps: void Phase::getMolecularWeights(double*)
  uses:
  - size_t Phase::nSpecies()

Individual YAML fields represent the following:

  • brief: Brief Doxygen docstring obtained from C++.

  • what: Type of recipe, as detected or defined in the corresponding CLib Function Types.

  • declaration: Full CLib function signature.

  • parameters: Mapping of CLib function arguments to respective docstrings.

  • returns: Docstring of value returned by CLib function.

  • wraps: Full signature of C++ function/method/variable implemented by CLib (if applicable).

  • uses: List of auxiliary C++ methods used by the CLib function (if applicable).

YAML Output Generation#

YAML output is generated by running the following command from the root folder of the Cantera source code:

scons doxygen && sourcegen --api=yaml --output=build/yaml

Generated YAML files are placed in the output folder build/yaml. Note that this step requires installation of sourcegen via python -m pip install -e interfaces/sourcegen.

YAML Source Generator Overview#

The YAML source generator is located in the interfaces/sourcegen/src/sourcegen/yaml folder. While the overall configuration follows available Generated CLib Headers, the YAML source generator introduces additional configuration options, as detailed below.

Configuration#

The configuration file config.yaml contains configuration options specific to the YAML interface. These options are common across all sourcegen variants and are based on the names of YAML configuration files.

  • ignore_files: A list of configuration files. Files listed here will be completely ignored during source generation.

  • ignore_funcs: A mapping of configuration file names to lists of recipe names. Functions listed in those files will not be scaffolded.

Implementation Details#

  • Templates for Scaffolding: Templates, powered by Jinja, are used to scaffold elements of the YAML output. The following files define these templates:

    • templates.yaml: Defines YAML code blocks within the output files.

    • template_output.yaml.in: Defines the template for output files.

  • Source Code: The implementation of the YAML source generator is contained in generator.py.

Extending the YAML API#

The YAML source generator relies on data used for the Generated CLib API and does not require additional configuration.

On this page
Show Source