Update doxygen (cont'd)

doc/doxygen/Doxyfile

@@ -51,7 +51,7 @@ PROJECT_BRIEF          =
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           =
+PROJECT_LOGO           = doc/sphinx/_static/images/cantera-icon.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -866,8 +866,7 @@ INPUT                  = src/base \
                          src/transport \
                          src/zeroD \
                          include \
-                         doc/doxygen \
-                         doc/doxygen/mainpage.md
+                         doc/doxygen
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -899,6 +898,7 @@ INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.h \
                          *.cpp \
                          *.txt \
+                         *.md \
                          *.dox
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
@@ -1511,7 +1511,7 @@ DISABLE_INDEX          = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
 # doxygen will group on one line in the generated HTML documentation.

doc/doxygen/mainpage.md

@@ -1,19 +1,22 @@
 # %Cantera C++ Reference
 
+> **Note:** This is the **%Cantera C++ API** documentation; for general
+> information on %Cantera, refer to [**Cantera's main website**](https://cantera.org).
+
 Use the menu at the top to view detailed documentation of the code, or use the
 following shortcuts:
 
-* Overview of [**Cantera Modules**](modules.html)
-* Index of [**Cantera Classes**](classes.html)
+* Overview of [**Cantera C++ Modules**](modules.html)
+* Index of [**Cantera C++ Classes**](classes.html)
 
 A topical overview is provided as follows:
 
-* @ref compobj (interface to %Cantera core objects)
+* @ref solnGroup (interface to %Cantera core objects)
 * @ref thermoprops (temperature, pressure, energy, ...)
 * @ref chemkinetics (reactions, rates of progress, reaction path analysis, ...)
 * @ref tranprops (diffusion, viscosity, thermal conductivity, ...)
-* @ref ZeroD (reactors, walls, flow devices, ...)
-* @ref onedim (flames, flow domains, boundaries, ...)
+* @ref zerodGroup (reactors, walls, flow devices, ...)
+* @ref onedGroup (flames, flow domains, boundaries, ...)
 * @ref physConstants (universal constants, built into %Cantera for convenience)
 
 For fundamental scientific theory used for the implementation of %Cantera, refer to the

doc/doxygen/thermoprops.dox

@@ -283,10 +283,9 @@
  *  phase. Functions which are defined at the %ThermoPhase level to give the
  *  user more information about the mechanical properties are:
  *
- *       - ThermoPhase::pressure()
- *       - ThermoPhase::isothermalCompressibility()
- *       - ThermoPhase::thermalExpansionCoeff()
- *       .
+ *  - ThermoPhase::pressure()
+ *  - ThermoPhase::isothermalCompressibility()
+ *  - ThermoPhase::thermalExpansionCoeff()
  *
  * <H3>
  * Treatment of the %Phase Potential and the electrochemical potential of a species
@@ -296,12 +295,12 @@
  *  is related to the chemical potential via
  *  the following equation,
  *
- *       \f[
- *            \zeta_{k}(T,P) = \mu_{k}(T,P) + z_k \phi_p
- *       \f]
+ *  \f[
+ *      \zeta_{k}(T,P) = \mu_{k}(T,P) + z_k \phi_p
+ *  \f]
  *
- *   where  \f$ \nu_k \f$ is the charge of species k, and \f$ \phi_p \f$ is
- *   the electric potential of phase p.
+ *  where \f$ \nu_k \f$ is the charge of species k, and \f$ \phi_p \f$ is
+ *  the electric potential of phase p.
  *
  *  The potential  \f$ \phi_p \f$ is tracked and internally stored within
  *  the base %ThermoPhase object. It constitutes a specification of the
@@ -315,9 +314,9 @@
  *  changed by the potential because many phases enforce charge
  *  neutrality:
  *
- *       \f[
- *            0 = \sum_k z_k X_k
- *       \f]
+ *  \f[
+ *      0 = \sum_k z_k X_k
+ *  \f]
  *
  *  Whether charge neutrality is necessary for a phase is also specified
  *  within the ThermoPhase object, by the function call

include/cantera/base/AnyMap.h

@@ -24,8 +24,13 @@ Emitter& operator<<(Emitter& out, const Cantera::AnyValue& rhs);
 namespace Cantera
 {
 
+//! @defgroup anyGroup Generic Containers
+//! Generic containers for storing data of any type.
+//! @ingroup ioGroup
+
 //! Base class defining common data possessed by both AnyMap and AnyValue
 //! objects.
+//! @ingroup anyGroup
 class AnyBase {
 public:
     AnyBase() = default;
@@ -75,6 +80,7 @@ class AnyMap;
  * - `bool`
  * - `std::string`
  * - `std::vector` of any of the above
+ * @ingroup anyGroup
  */
 class AnyValue : public AnyBase
 {
@@ -414,6 +420,7 @@ std::vector<AnyMap>& AnyValue::asVector<AnyMap>(size_t nMin, size_t nMax);
  *     // access using asVector<std::string>
  * }
  * ```
+ * @ingroup anyGroup
  */
 class AnyMap : public AnyBase
 {

include/cantera/base/Interface.h

@@ -17,7 +17,7 @@ namespace Cantera
 /*!
  * Instances of class Interface represent reacting 2D surfaces between bulk 3D phases,
  * or 1D edges where multiple surfaces (and bulk phases) meet.
- * @ingroup compobj
+ * @ingroup solnGroup
  */
 class Interface : public Solution
 {
@@ -66,7 +66,7 @@ class Interface : public Solution
  *                 phases kinetics. If empty, adjacent phases will be instantiated based
  *                 on the phase definition.
  * @returns an initialized Interface object.
- * @ingroup compobj
+ * @ingroup solnGroup
  */
 shared_ptr<Interface> newInterface(const std::string& infile,
     const std::string& name="", const std::vector<std::string>& adjacent={});
@@ -82,7 +82,7 @@ shared_ptr<Interface> newInterface(const std::string& infile,
  * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
  *                 phases will be instantiated based on the phase definition.
  * @returns an initialized Interface object.
- * @ingroup compobj
+ * @ingroup solnGroup
  */
 shared_ptr<Interface> newInterface(const std::string& infile,
     const std::string& name, const std::vector<shared_ptr<Solution>>& adjacent);
@@ -98,7 +98,7 @@ shared_ptr<Interface> newInterface(const std::string& infile,
  * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
  *                 phases will be instantiated based on the phase definition.
  * @returns an initialized Interface object.
- * @ingroup compobj
+ * @ingroup solnGroup
  */
 shared_ptr<Interface> newInterface(AnyMap& phaseNode, const AnyMap& rootNode=AnyMap(),
     const std::vector<shared_ptr<Solution>>& adjacent={});

include/cantera/base/Solution.h

@@ -17,7 +17,7 @@ class Kinetics;
 class Transport;
 class ExternalHandle;
 
-//! @defgroup compobj Objects Representing Phases
+//! @defgroup solnGroup Objects Representing Phases
 //! High-level interface to %Cantera's core objects.
 
 //! A container class for chemically-reacting solutions.
@@ -38,7 +38,7 @@ class ExternalHandle;
  * @code
  *    shared_ptr<Solution> sol = newSolution("gri30.yaml", "gri30");
  * @endcode
- * @ingroup compobj
+ * @ingroup solnGroup
  */
 class Solution : public std::enable_shared_from_this<Solution>
 {
@@ -182,7 +182,7 @@ class Solution : public std::enable_shared_from_this<Solution>
  *                 phases kinetics. If empty, adjacent phases will be instantiated based
  *                 on the phase definition.
  * @returns an initialized Solution object.
- * @ingroup compobj
+ * @ingroup solnGroup
  */
 shared_ptr<Solution> newSolution(const std::string& infile, const std::string& name,
     const std::string& transport, const std::vector<std::string>& adjacent);
@@ -199,7 +199,7 @@ shared_ptr<Solution> newSolution(const std::string& infile, const std::string& n
  * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
  *                 phases will be instantiated based on the phase definition.
  * @returns an initialized Solution object.
- * @ingroup compobj
+ * @ingroup solnGroup
  */
 shared_ptr<Solution> newSolution(const std::string& infile,
                                  const std::string& name="",
@@ -223,7 +223,7 @@ shared_ptr<Solution> newSolution(const std::string& infile,
  *                 a phase may be adjacent to multiple other phases but should be
  *                 instantiated only once.
  * @returns an initialized Solution object.
- * @ingroup compobj
+ * @ingroup solnGroup
  */
 shared_ptr<Solution> newSolution(
     const AnyMap& phaseNode, const AnyMap& rootNode=AnyMap(),

include/cantera/base/SolutionArray.h

@@ -27,7 +27,7 @@ class ThermoPhase;
  * HDF container files using the save() and restore() methods. In addition, there is
  * limited support for CSV files.
  * @since  New in Cantera 3.0.
- * @ingroup compobj
+ * @ingroup solnGroup
  */
 class SolutionArray
 {

include/cantera/base/Units.h

@@ -1,7 +1,7 @@
 /**
  * @file Units.h
  * Header for unit conversion utilities, which are used to translate
- * user input from input files (See \ref inputfiles and
+ * user input from input files (See \ref inputGroup and
  * class \link Cantera::Units Units\endlink).
  */
 
@@ -19,12 +19,17 @@ namespace Cantera
 class AnyValue;
 class AnyMap;
 
+//! @defgroup unitsGroup Unit Conversion
+//! Unit conversion utilities.
+//! @ingroup ioGroup
+
 //! A representation of the units associated with a dimensional quantity.
 /*!
  * Used for converting quantities between unit systems and checking for
  * dimensional consistency. Units objects are mainly used within UnitSystem
  * class to convert values from a user-specified Unit system to Cantera's
  * base units (SI + kmol).
+ * @ingroup unitsGroup
  */
 class Units
 {
@@ -94,6 +99,7 @@ class Units
  *
  * @warning This class is an experimental part of the %Cantera API and
  *    may be changed or removed without notice.
+ * @ingroup unitsGroup
  */
 struct UnitStack
 {
@@ -157,7 +163,7 @@ struct UnitStack
  * expressed as either energy per quantity, energy (for example, eV), or temperature by
  * applying a factor of the Avogadro number or the gas constant where needed.
  *
- * @ingroup inputfiles
+ * @ingroup unitsGroup
  */
 class UnitSystem
 {

include/cantera/base/YamlWriter.h

@@ -18,7 +18,12 @@ class ThermoPhase;
 class Kinetics;
 class Transport;
 
+//! @defgroup serializeGroup Serialization
+//! Classes and functions related to serialization of %Cantera objects
+//! @ingroup ioGroup
+
 //! A class for generating full YAML input files from multiple data sources
+//! @ingroup serializeGroup
 class YamlWriter
 {
 public:

include/cantera/base/clockWC.h

@@ -14,6 +14,8 @@
 namespace Cantera
 {
 
+//! @defgroup globalUtilFuncs Global Utility Functions
+
 //! The class provides the wall clock timer in seconds
 /*!
  * This routine relies on the ANSI C routine, clock(), for its basic operation.

include/cantera/base/ctexceptions.h

@@ -19,7 +19,7 @@ namespace Cantera
 {
 
 /**
- * @defgroup debugGroup Errors & Diagnostics
+ * @defgroup debugGroup Errors and Diagnostics
 */
 
 /*!

include/cantera/base/global.h

@@ -1,11 +1,11 @@
 /**
  * @file global.h
  * This file contains definitions for utility functions and text for modules,
- * inputfiles and logging, (see \ref inputfiles, and \ref logGroup).
+ * inputfiles and logging, (see \ref inputGroup, and \ref logGroup).
  *
  * These functions store some parameters in global storage that are accessible
  * at all times from the calling application. Contains module definitions for
- *     -  inputfiles  (see \ref inputfiles)
+ *     -  inputfiles  (see \ref inputGroup)
  *     -  text logs  (see \ref logGroup)
  */
 
@@ -24,40 +24,47 @@ namespace Cantera
 class Logger;
 class AnyMap;
 
+//! @defgroup ioGroup File Input/Output
+//! @details Classes and functions used for reading and writing of %Cantera input files.
+
 /*!
- * @defgroup inputfiles Input File Handling
+ * @defgroup inputGroup Input File Handling
+ * @brief Handling of %Cantera input files.
  *
  * The properties of phases and interfaces are specified in text files. These
- * procedures handle various aspects of reading these files.
+ * procedures handle various aspects of reading these files. Input files should be read
+ * using the newSolution() or newInterface() service functions (see @ref solnGroup).
  *
  * For input files not specified by an absolute pathname, %Cantera searches
  * for input files along a path that includes platform-specific default
- * locations, and possibly user-specified locations.
- *
- * The current directory (".") is always searched first. Then, on Windows, the
- * registry is checked to find the Cantera installation directory, and the
- * 'data' subdirectory of the installation directory will be added to the search
- * path.
- *
- * On any platform, if environment variable CANTERA_DATA is set to a directory
- * name or a list of directory names separated with the OS-dependent path
- * separator (that is, ";" on Windows, ":" elsewhere), then these directories will
- * be added to the search path.
+ * locations, and possibly user-specified locations:
  *
- * Finally, the location where the data files were installed when
- * %Cantera was built is added to the search path.
- *
- * Additional directories may be added by calling function addDirectory.
+ *    - The current directory \c "." is always searched first. Then, on Windows, the
+ *      registry is checked to find the %Cantera installation directory, and the
+ *      \c data subdirectory of the installation directory will be added to the search
+ *      path.
+ *    - On any platform, if environment variable \c CANTERA_DATA is set to a directory
+ *      name or a list of directory names separated with the OS-dependent path
+ *      separator (that is, \c ";" on Windows, \c ":" elsewhere), then these directories
+ *      will be added to the search path.
+ *    - Finally, the location where the data files were installed when %Cantera was
+ *      built is added to the search path.
+ *    - Additional directories may be added dynamically by calling the addDirectory()
+ *      function.
  *
  * %Cantera input files are written using YAML syntax. For more information on using
- * YAML files in Cantera, see the
- * <a href="https://cantera.org/tutorials/yaml/defining-phases.html">YAML Users' Guide</a>
- * or the <a href="../../../../sphinx/html/yaml/index.html">YAML Input File API Reference</a>.
- *
- * %Cantera provides the `ck2yaml` tool for converting Chemkin-format mechanisms to the
- * YAML format. The scripts `cti2yaml.py` and `ctml2yaml.py` can be used to convert
- * legacy CTI and XML input files (from Cantera 2.6 and earlier) to the YAML format.
+ * YAML files in %Cantera, see the
+ * [YAML Users' Guide](https://cantera.org/tutorials/yaml/defining-phases.html)
+ * or the [YAML Input File API Reference](../../../../sphinx/html/yaml/index.html).
+ * %Cantera provides the
+ * [`ck2yaml`](https://cantera.org/tutorials/ck2yaml-tutorial.html)
+ * tool for converting Chemkin-format mechanisms to the YAML format. The utilities
+ * [`cti2yaml`](https://cantera.org/tutorials/legacy2yaml.html#cti2yaml) and
+ * [`ctml2yaml`](https://cantera.org/tutorials/legacy2yaml.html#ctml2yaml) should be
+ * used to convert legacy CTI and XML input files (from %Cantera 2.6 and earlier) to the
+ * YAML format.
  *
+ * @ingroup ioGroup
  * @{
  */