From 75c99c86a15d2080a12302e8a13f8d1262f91533 Mon Sep 17 00:00:00 2001
From: Ingmar Schoegl <ischoegl@lsu.edu>
Date: Fri, 7 Jul 2023 15:02:14 -0600
Subject: [PATCH] [docs] Switch to markdown mainfile

Supported for doxygen 1.8.3 and later (released 2012)
---
 doc/doxygen/Cantera.txt             |  6 ------
 doc/doxygen/Doxyfile                |  5 +++--
 doc/doxygen/mainpage.md             | 23 +++++++++++++++++++++++
 include/cantera/base/Solution.h     |  4 ++--
 include/cantera/zeroD/ReactorBase.h |  7 ++++---
 5 files changed, 32 insertions(+), 13 deletions(-)
 delete mode 100644 doc/doxygen/Cantera.txt
 create mode 100644 doc/doxygen/mainpage.md

diff --git a/doc/doxygen/Cantera.txt b/doc/doxygen/Cantera.txt
deleted file mode 100644
index 63c13a8f8fa..00000000000
--- a/doc/doxygen/Cantera.txt
+++ /dev/null
@@ -1,6 +0,0 @@
-/**
-\mainpage Cantera C++ Reference
-
-Use the menu at the top to view detailed documentation of the code.
-
-*/
diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile
index b5cc3e82317..269b94c0728 100644
--- a/doc/doxygen/Doxyfile
+++ b/doc/doxygen/Doxyfile
@@ -866,7 +866,8 @@ INPUT                  = src/base \
                          src/transport \
                          src/zeroD \
                          include \
-                         doc/doxygen
+                         doc/doxygen \
+                         doc/doxygen/mainpage.md
 
 # 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
@@ -1027,7 +1028,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = mainpage.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
diff --git a/doc/doxygen/mainpage.md b/doc/doxygen/mainpage.md
new file mode 100644
index 00000000000..deb690e11d2
--- /dev/null
+++ b/doc/doxygen/mainpage.md
@@ -0,0 +1,23 @@
+# %Cantera C++ Reference
+
+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)
+
+A topical overview is provided as follows:
+
+* @ref compobj (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 physConstants (universal constants, built into %Cantera for convenience)
+
+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).
diff --git a/include/cantera/base/Solution.h b/include/cantera/base/Solution.h
index c0c3de68e6f..4b8dcddcc07 100644
--- a/include/cantera/base/Solution.h
+++ b/include/cantera/base/Solution.h
@@ -17,8 +17,8 @@ class Kinetics;
 class Transport;
 class ExternalHandle;
 
-//! @defgroup compobj Composite Objects
-//! Composite objects create a high-level interface to Cantera's core objects.
+//! @defgroup compobj Objects Representing Phases
+//! High-level interface to %Cantera's core objects.
 
 //! A container class for chemically-reacting solutions.
 /*!
diff --git a/include/cantera/zeroD/ReactorBase.h b/include/cantera/zeroD/ReactorBase.h
index 81591d848ea..71b5e15237c 100644
--- a/include/cantera/zeroD/ReactorBase.h
+++ b/include/cantera/zeroD/ReactorBase.h
@@ -15,9 +15,10 @@ namespace Cantera
 
 //! @defgroup ZeroD Zero-dimensional reactor networks
 //!
-//! See https://cantera.org/science/reactors.html for a description of the governing
-//! equations for specific reactor types and the methods used for solving networks of
-// interconnected reactors.
+//! See the [Reactor Science](https://cantera.org/science/reactors/reactors.html)
+//! section of the %Cantera website for a description of the governing equations for
+//! specific reactor types and the methods used for solving networks of interconnected
+//! reactors.
 
 class FlowDevice;
 class WallBase;