Consolidate YAML API documentation in doxygen

doc/doxygen/mainpage.md

@@ -1,15 +1,17 @@
-# %Cantera C++ Reference
+@mainpage %Cantera Developer API
 
 > **Note:** This is the **%Cantera Developer API** documentation; for general
 > information on %Cantera, refer to [**cantera.org**](https://cantera.org).
+> The %Cantera source code is hosted on [GitHub](https://github.com/Cantera/cantera).
 
 Use sidebar or menu at the top to view detailed documentation of the code, or
 use the following shortcuts:
 
 * Overview of [**Cantera C++ Modules**](modules.html)
 * Index of [**Cantera C++ Classes**](classes.html)
+* @ref sec-yaml-documentation
 
-A topical overview is provided as follows:
+A topical overview of C++ modules is provided as follows:
 
 * @ref solnGroup (interface to %Cantera core objects)
 * @ref thermoprops (temperature, pressure, energy, ...)
@@ -22,5 +24,3 @@ A topical overview is provided as follows:
 For fundamental scientific theory used for the implementation of %Cantera, refer to the
 [Cantera Science Section](https://cantera.org/science/index.html) of the
 [Cantera Website](https://cantera.org).
-
-The %Cantera source code is hosted on [GitHub](https://github.com/Cantera/cantera).

doc/doxygen/yaml.md

@@ -0,0 +1,26 @@
+@page sec-yaml-documentation %Cantera YAML Documentation
+
+> **Note:** %Cantera provides @ref sec-yaml-conversion to generate YAML files
+> from Chemkin input data as well as legacy %Cantera formats.
+
+This short guide describes %Cantera YAML input files that define phases and
+interfaces for use in %Cantera simulations. Each link below represents an entry
+point to the @subpage sec-yaml-api; while you certainly can read them in order,
+you can also jump to whichever section addresses your current needs. If you need
+tips on troubleshooting the YAML file syntax rules, please look at the
+@subpage sec-yaml-format-tutorial.
+
+-   <b>@ref sec-yaml-general</b> -
+    Structure of a %Cantera YAML input file.
+-   <b>@ref sec-yaml-phases</b> -
+    For each phase or interface that appears in a problem, a corresponding
+    entry should be present in the input file(s). Phase entries specify lists
+    of elements, species and reactions, as well as other relevant parameters.
+-   <b>@ref sec-yaml-species</b> -
+    For each species declared as part of a phase description, thermodynamic
+    properties and other data need to be defined.
+-   <b>@ref sec-yaml-reactions</b> -
+    %Cantera supports a number of different types of reactions, including
+    several types of homogeneous reactions, surface reactions, and
+    electrochemical reactions. For each, there is a corresponding entry
+    type.

doc/doxygen/yaml/elements.md

@@ -0,0 +1,52 @@
+@page sec-yaml-elements Element Entries
+
+[TOC]
+
+# Overview
+
+%Cantera provides built-in definitions for the chemical elements, including values for
+their atomic weights taken from IUPAC / CIAAW. These elements can be used by specifying
+the corresponding atomic symbols when specifying the composition of species. `element`
+entries are needed only when defining custom elements that are not standard chemical
+elements, or defining specific isotopes.
+
+In order to give a name to a particular isotope or a virtual element
+representing a surface site, a custom `element` entry can be used. The
+default location for `element` entries is the `elements` section of the
+input file. Elements defined in this section will automatically be
+considered for addition to phases defined in the same file. Elements can
+be defined in other sections of the input file if those sections are
+named explicitly in the `elements` field of the phase definition.
+
+**Example:**
+
+```yaml
+elements:
+- symbol: C13
+  atomic-weight: 13.003354826
+  atomic-number: 12
+- symbol: O-18
+  atomic-weight: 17.9991603
+```
+
+# Element API Reference
+
+The fields of an `element` entry are:
+
+<b>`symbol`</b>
+
+The symbol used for the element, as used when specifying the
+composition of species.
+
+<b>`atomic-weight`</b>
+
+The atomic weight of the element, in unified atomic mass units
+(dalton).
+
+<b>`atomic-number`</b>
+
+The atomic number of the element. Optional.
+
+<b>`entropy298`</b>
+
+The standard molar entropy of the element at 298.15 K. Optional.

doc/doxygen/yaml/general.md

@@ -0,0 +1,43 @@
+@page sec-yaml-general General File Structure
+
+The top level of a %Cantera YAML input file is a mapping that defines different input
+file sections. Each section consists of a list of mappings that define objects of the
+same type, such as reactions, species, phases, or elements. The `phases` section of
+an input file contains all of the phase definitions. Multiple sections
+containing reaction, species, or element definitions can be used. The
+specific names `reactions`, `species`, and `elements` are used as defaults when looking
+for @ref sec-yaml-reactions, @ref sec-yaml-species, and @ref sec-yaml-elements to add to
+a phase. %Cantera uses SI input units by default, although input values can be
+provided using a number of different units, as described in the
+@ref sec-yaml-units-default section.
+
+A simple input file has the following structure:
+
+```yaml
+description: |-
+  Optional description of the input file.
+
+# units: optional unit settings used for input data
+
+phases:
+- name: spam
+  thermo: ideal-gas
+  # Additional fields come after this
+- name: green-eggs
+  thermo: model-name
+  # Additional fields come after this
+
+species:
+- name: A
+  # Additional fields come after this
+- name: B
+  # Additional fields come after this
+- name: C
+  # Additional fields come after this
+
+reactions:
+- equation: A + B <=> C + D
+  # Additional fields come after this
+- equation: A + C <=> 2 D
+  # Additional fields come after this
+```