From 6eb4f08907a0692376aa4ed3c6c4cb362f217dc9 Mon Sep 17 00:00:00 2001
From: Ray Speth <speth@mit.edu>
Date: Wed, 20 Sep 2023 14:49:35 -0400
Subject: [PATCH] Add clib example to sphinx-gallery

---
 doc/SConscript          | 7 +++++++
 doc/sphinx/conf.py      | 5 ++++-
 doc/sphinx/index.rst    | 1 +
 samples/clib/README.rst | 6 ++++++
 samples/clib/demo.c     | 8 ++++++--
 5 files changed, 24 insertions(+), 3 deletions(-)
 create mode 100644 samples/clib/README.rst

diff --git a/doc/SConscript b/doc/SConscript
index 9b74cd281..729abc836 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -146,6 +146,13 @@ if localenv['sphinx_docs']:
                     localenv.Command(f"#build/doc/samples/fortran/{fort_file.name}",
                                      fort_file, Copy("$TARGET", "$SOURCE")))
 
+    # Gather clib sample files
+    clib_files = Glob("#samples/clib/*.c") + [File("#samples/clib/README.rst")]
+    for clib_file in clib_files:
+        env.Depends(sphinxdocs,
+                    localenv.Command(f"#build/doc/samples/clib/{clib_file.name}",
+                                     clib_file, Copy("$TARGET", "$SOURCE")))
+
     # Create a list of MATLAB classes to document. This uses the NamedTuple
     # structure defined at the top of the file. The @Data and @Utilities
     # classes are fake classes for the purposes of documentation only. Each
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
index 84c66c519..2ee5546cf 100644
--- a/doc/sphinx/conf.py
+++ b/doc/sphinx/conf.py
@@ -49,17 +49,19 @@ extensions = [
 
 sphinx_gallery_conf = {
     'filename_pattern': '\.py',
-    'example_extensions': {'.py', '.cpp', '.h', '.f', '.f90'},
+    'example_extensions': {'.py', '.cpp', '.h', '.c', '.f', '.f90'},
     "filetype_parsers": {'.h': 'C++'},
     'image_srcset': ["2x"],
     'examples_dirs': [
        '../samples/python/',
        '../samples/cxx/',
+       '../samples/clib/',
        '../samples/fortran/',
     ],
     'gallery_dirs': [
        'examples/python',
        'examples/cxx',
+       'examples/clib',
        'examples/fortran',
     ],
     'reference_url': {
@@ -122,6 +124,7 @@ tags_page_header = "Examples with this tag:"
 tags_badge_colors = {
     "Python": "secondary",
     "C++": "secondary",
+    "C": "secondary",
     "Fortran 77": "secondary",
     "Fortran 90": "secondary",
 }
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index deed1da89..66045454c 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -17,6 +17,7 @@ format.
 
    examples/python/index
    examples/cxx/index
+   examples/clib/index
    examples/fortran/index
 
    _tags/tagsindex
diff --git a/samples/clib/README.rst b/samples/clib/README.rst
new file mode 100644
index 000000000..3b6b460fa
--- /dev/null
+++ b/samples/clib/README.rst
@@ -0,0 +1,6 @@
+C Examples
+==========
+
+These examples demonstrate the usage of Cantera's C interface library, ``clib``,
+which can also be used to call Cantera from other languages that are able to
+call C functions.
diff --git a/samples/clib/demo.c b/samples/clib/demo.c
index 770c567e9..51cb896d4 100644
--- a/samples/clib/demo.c
+++ b/samples/clib/demo.c
@@ -1,11 +1,13 @@
-/**
+/*
  * CLib Demo
+ * =========
  *
  * This program illustrates using Cantera's C-library interface to compute
  * thermodynamic, kinetic, and transport properties of a gas mixture. In addition,
  * a simple reactor network simulation is illustrated.
  *
- * Keywords: tutorial, equilibrium, thermodynamics, kinetics, transport, reactor network
+ * .. tags:: C, tutorial, equilibrium, thermodynamics, kinetics, transport,
+ *           reactor network
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or
@@ -16,6 +18,7 @@
 
 #include <stdio.h>
 
+// sphinx_gallery_start_ignore
 // The following header files are not used by this example, but are nevertheless added
 // here to ensure C-compatibility of Cantera's clib includes in continuous testing.
 #include "cantera/clib/ctfunc.h"
@@ -23,6 +26,7 @@
 #include "cantera/clib/ctonedim.h"
 #include "cantera/clib/ctrpath.h"
 #include "cantera/clib/ctsurf.h"
+// sphinx_gallery_end_ignore
 
 void exit_with_error()
 {