Render examples using Sphinx-gallery

.github/workflows/main.yml

@@ -317,16 +317,22 @@ jobs:
       - name: Install Apt dependencies
         run: |
           sudo apt update
-          sudo apt install libboost-dev doxygen graphviz texlive-bibtex-extra
+          sudo apt install libboost-dev doxygen graphviz texlive-bibtex-extra \
+            libblas-dev liblapack-dev libhdf5-dev libfmt-dev libsundials-dev
       - name: Upgrade pip
         run: python3 -m pip install -U pip setuptools wheel
       - name: Install Python dependencies
         run: |
-          python3 -m pip install ruamel.yaml scons numpy cython sphinx==5.1.1 \
-          sphinxcontrib-matlabdomain sphinxcontrib-doxylink pint \
-          pydata-sphinx-theme==0.13.3 sphinx-argparse
-      - name: Build Cantera with documentation
-        run: python3 `which scons` build -j2 doxygen_docs=y sphinx_docs=y debug=n optimize=n use_pch=n
+          python3 -m pip install ruamel.yaml scons numpy cython sphinx==6.2.1 \
+            sphinxcontrib-matlabdomain sphinxcontrib-doxylink pint \
+            pydata-sphinx-theme==0.13.3 sphinx-argparse sphinx_design matplotlib \
+            pandas scipy
+          python3 -m pip install "git+https://github.com/sphinx-gallery/sphinx-gallery.git@master"
+          python3 -m pip install "git+https://github.com/Cantera/sphinx-tags.git@main"
+      - name: Build Cantera
+        run: python3 `which scons` build -j2 debug=n optimize=y use_pch=n
+      - name: Build documentation
+        run: python3 `which scons` sphinx doxygen logging=debug
       - name: Ensure 'scons help' options work
         run: |
           python3 `which scons` help --options
@@ -335,18 +341,20 @@ jobs:
       - name: Parse configuration options from SConstruct as reST
         run: |
           python3 `which scons` help --restructured-text --dev --output=config-options-dev.rst
-          mkdir build/docs/scons
-          mv config-options-dev.rst build/docs/scons/
+          mkdir build/doc/scons
+          mv config-options-dev.rst build/doc/scons/
       - name: Create archive for docs output
         run: |
           cd build
-          tar -czf docs.tar.gz docs
+          tar -czf docs.tar.gz doc
+        if: failure() || success()
       - name: Store archive of docs output
         uses: actions/upload-artifact@v3
         with:
           path: build/docs.tar.gz
           name: docs
-          retention-days: 2
+          retention-days: 14
+        if: failure() || success()
       # The known_hosts key is generated with `ssh-keygen -F cantera.org` from a
       # machine that has previously logged in to cantera.org and trusts
       # that it logged in to the right machine
@@ -362,7 +370,7 @@ jobs:
           RSYNC_USER: "ctdeploy"
           RSYNC_SERVER: "cantera.org"
           RSYNC_DEST: "cantera/documentation/dev"
-          DOCS_OUTPUT_DIR: "./build/docs/"
+          DOCS_OUTPUT_DIR: "./build/doc/"
         run: |
           rsync -avzP --checksum --exclude='*.map' --exclude='*.md5' \
           --exclude='/doxygen/xml' --delete --delete-excluded \

.gitignore

@@ -51,5 +51,3 @@ environment.y*
 coverage/
 coverage.info
 .coverage
-doc/sphinx/matlab/*.rst
-!doc/sphinx/matlab/index.rst

AUTHORS

@@ -34,7 +34,7 @@ Benjamin Kee (@lionkey)
 Cory Kinney (@corykinney)
 Gandhali Kogekar (@gkogekar)
 Daniel Korff (@korffdm), Colorado School of Mines
-Corey R. Randall (@c-randall), Colorado School of Mines
+Ashwin Kumar (mgashwinkumar), Virginia Tech
 Jon Kristofer
 Samesh Lakothia (@sameshl)
 Kyle Linevitch, Jr. (@KyleLinevitchJr)
@@ -43,13 +43,15 @@ Nicholas Malaya (@nicholasmalaya), University of Texas at Austin
 Thanasis Mattas (@ThanasisMattas), Aristotle University of Thessaloniki
 Manik Mayur (@manikmayur)
 Evan McCorkle
+Joseph Meadows, Virginia Tech
 Phillip Mestas (@xMestas)
 Ivan Mitrichev (@imitrichev), Mendeleev University of Chemical Technology of Russia
 Harry Moffat (@hkmoffat), Sandia National Laboratory
 Christopher Neal (@wandadars)
 Kyle Niemeyer (@kyleniemeyer), Oregon State University
 Paul Northrop (@pwcnorthrop)
 Sebastian Pinnau (@spinnau)
+Corey R. Randall (@c-randall), Colorado School of Mines
 Andreas Rücker (@cannondale1492)
 Jeff Santner (@jsantner)
 Satyam Saxena (@CyberDrudge)

doc/SConscript

@@ -97,7 +97,7 @@ def get_function_name(function_string):
         return sig
 
 if localenv['doxygen_docs']:
-    docs = build(localenv.Command('#build/docs/doxygen/html/index.html',
+    docs = build(localenv.Command('#build/doc/doxygen/html/index.html',
                                   'doxygen/Doxyfile', 'doxygen $SOURCE'))
     env.Depends(docs, env.Glob('#doc/doxygen/*') +
                       multi_glob(env, '#include/cantera', 'h') +
@@ -106,22 +106,57 @@ if localenv['doxygen_docs']:
 
     env.Alias('doxygen', docs)
     install(localenv.RecursiveInstall, '$inst_docdir/doxygen/html',
-            '#/build/docs/doxygen/html', exclude=['\\.map', '\\.md5'])
+            '#/build/doc/doxygen/html', exclude=['\\.map', '\\.md5'])
 
 if localenv['sphinx_docs']:
     def build_sphinx(target, source, env):
         cmd = [env['sphinx_cmd']] + env['sphinx_options'].split()
-        cmd += ('-b', 'html', '-d', 'build/docs/sphinx/doctrees', 'doc/sphinx',
-                'build/docs/sphinx/html')
+        if env['logging'] == 'debug':
+            cmd.append('-v')
+        cmd += ('-b', 'html', '-d', 'build/doc/sphinx/doctrees', 'build/doc/sphinx',
+                'build/doc/sphinx/html')
         code = subprocess.call(cmd, env=env['ENV'])
         if code:
             raise Errors.BuildError(target, action=env['sphinx_cmd'])
 
-    sphinxdocs = build(localenv.Command('#build/doc/sphinx/html/index.html',
+    # RecursiveInstall knows to copy modified files, unlike Copy
+    copy_sphinx = localenv.RecursiveInstall("#build/doc/sphinx", "sphinx")
+    copy_python_samples = localenv.RecursiveInstall("#build/doc/samples/python",
+                                                    "#samples/python")
+    copy_matlab_ex_samples = localenv.RecursiveInstall(
+        "#build/doc/samples/matlab_experimental", "#samples/matlab_experimental")
+
+    sphinxdocs = build(localenv.Command('build/doc/sphinx/html/index.html',
         'sphinx/conf.py', build_sphinx))
     env.Alias('sphinx', sphinxdocs)
+    env.Depends(sphinxdocs, copy_sphinx)
+    env.Depends(sphinxdocs, [copy_python_samples, copy_matlab_ex_samples])
     env.Depends(sphinxdocs, env['python_module'])
 
+    # Gather all C++ samples into a single directory so they can be presented a single
+    # sub-gallery by sphinx-gallery
+    cxxfiles = (Glob("#samples/cxx/*/*.cpp") + Glob("#samples/cxx/*/*.h")
+                + Glob("#samples/cxx/*.rst"))
+    for cxxfile in cxxfiles:
+        env.Depends(sphinxdocs,
+                    localenv.Command(f"#build/doc/samples/cxx/{cxxfile.name}", cxxfile,
+                                     Copy("$TARGET", "$SOURCE")))
+
+    # Gather all Fortran (F77 and F90) samples into a single directory
+    fort_files = (Glob("#samples/f77/*.f") + Glob("#samples/f77/*.cpp")
+                  + Glob("#samples/f90/*.f90") + Glob("#samples/f90/README.rst"))
+    for fort_file in fort_files:
+        env.Depends(sphinxdocs,
+                    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
@@ -208,7 +243,7 @@ if localenv['sphinx_docs']:
         # every time the source is changed, we don't want to have to commit the
         # change in the rst file as well as the source - too much code churn. So
         # we use a template and a SubstFile directive.
-        c = tempenv.SubstFile('#doc/sphinx/matlab/%s.rst' % page.name,
+        c = tempenv.SubstFile('#build/doc/sphinx/matlab/%s.rst' % page.name,
                               '#doc/sphinx/matlab/matlab-template.rst.in')
         build(c)
         localenv.Depends(sphinxdocs, c)
@@ -217,4 +252,4 @@ if localenv['sphinx_docs']:
     if localenv['doxygen_docs']:
         localenv.Depends(sphinxdocs, docs)
     install(localenv.RecursiveInstall, '$inst_docdir/sphinx/html',
-            '#/build/docs/sphinx/html')
+            '#build/doc/sphinx/html')

doc/doxygen/Doxyfile

@@ -58,7 +58,7 @@ PROJECT_LOGO           = doc/sphinx/_static/images/cantera-icon.png
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = build/docs/doxygen
+OUTPUT_DIRECTORY       = build/doc/doxygen
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -2197,7 +2197,7 @@ TAGFILES               =
 # tag file that is based on the input files it reads. See section "Linking to
 # external documentation" for more information about the usage of tag files.
 
-GENERATE_TAGFILE       = build/docs/Cantera.tag
+GENERATE_TAGFILE       = build/doc/Cantera.tag
 
 # If the ALLEXTERNALS tag is set to YES, all external class will be listed in
 # the class index. If set to NO, only the inherited external classes will be

doc/example-keywords.py

@@ -3,7 +3,7 @@
 """
 example-keywords.py
 
-Parse Cantera examples for "Keywords" declarations to ensure that all examples have
+Parse Cantera examples for keyword (tag) declarations to ensure that all examples have
 keyword definitions and to help maintain consistency in the keywords chosen.
 
 Usage:
@@ -42,7 +42,7 @@ def get_python_keywords(filename):
         return False
     docstring = match.group(2) + "\n\n"
 
-    match = re.search(r"\s*Keywords:(.*?)\n\n", docstring, re.DOTALL | re.MULTILINE)
+    match = re.search(r"\s*\.\. tags::(.*?)\n\n", docstring, re.DOTALL | re.MULTILINE)
     if not match:
         EXIT_CODE = 1
         logging.warning(f"No keywords found in {filename}")
@@ -59,7 +59,7 @@ def get_matlab_keywords(filename):
     comma separated.
     """
     text = Path(filename).read_text()
-    match = re.search(r"(?:%.*?\n)+", text, re.DOTALL | re.MULTILINE)
+    match = re.search(r"(?:\s*%.*?\n)+", text, re.DOTALL | re.MULTILINE)
     global EXIT_CODE
     if not match:
         EXIT_CODE = 1
@@ -68,7 +68,7 @@ def get_matlab_keywords(filename):
     docstring = match.group(0) + "\n\n"
     docstring = "\n".join(line.lstrip("% ") for line in docstring.splitlines())
 
-    match = re.search(r"\s*Keywords:(.*?)\n\n", docstring, re.DOTALL | re.MULTILINE)
+    match = re.search(r"\s*\.\. tags::(.*?)\n\n", docstring, re.DOTALL | re.MULTILINE)
     if not match:
         EXIT_CODE = 1
         logging.warning(f"No keywords found in {filename}")
@@ -79,15 +79,15 @@ def get_matlab_keywords(filename):
 
 def get_cxx_keywords(filename):
     text = Path(filename).read_text()
-    match = re.search(r"\/\*[!\*](.*?)\*\/", text, re.DOTALL | re.MULTILINE)
+    match = re.search(r"\/\*(.*?)\*\/", text, re.DOTALL | re.MULTILINE)
     global EXIT_CODE
     if not match:
         EXIT_CODE = 1
         logging.error(f"Couldn't parse docstring for {filename}")
         return False
     docstring = match.group(1) + "\n\n"
     docstring = "\n".join(line.lstrip("* ") for line in docstring.splitlines())
-    match = re.search(r"\s*Keywords:(.*?)\n\n", docstring, re.DOTALL | re.MULTILINE)
+    match = re.search(r"\s*\.\. tags::(.*?)\n\n", docstring, re.DOTALL | re.MULTILINE)
     if not match:
         EXIT_CODE = 1
         logging.warning(f"No keywords found in {filename}")
@@ -109,7 +109,7 @@ def get_fortran_keywords(filename, comment_char):
     docstring = "\n".join(line.lstrip(f"{comment_char} ")
                           for line in docstring.splitlines())
 
-    match = re.search(r"\s*Keywords:(.*?)\n\n", docstring, re.DOTALL | re.MULTILINE)
+    match = re.search(r"\s*\.\. tags::(.*?)\n\n", docstring, re.DOTALL | re.MULTILINE)
     if not match:
         EXIT_CODE = 1
         logging.warning(f"No keywords found in {filename}")
@@ -137,7 +137,7 @@ def get_all_keywords():
                 if kw:
                     all_keywords.update(kw)
 
-    for f in (cantera_root / "samples/matlab").glob("*.m"):
+    for f in (cantera_root / "samples/matlab_experimental").glob("*.m"):
         if f.name in skip:
             continue
         kw = get_matlab_keywords(f)
@@ -149,7 +149,8 @@ def get_all_keywords():
             continue
         if d.is_dir():
             for f in d.glob("*.cpp"):
-                all_keywords.update(get_cxx_keywords(f))
+                if kw := get_cxx_keywords(f):
+                    all_keywords.update(kw)
 
     for f in (cantera_root / "samples/f77").glob("*.f"):
         if f.name in skip:
@@ -187,7 +188,7 @@ def save_keywords():
     Save an updated version of the known keywords list based on keywords appearing in
     any of the examples.
     """
-    found_kw = "\n".join(sorted(get_all_keywords()) + [""])
+    found_kw = "\n".join(sorted(get_all_keywords(), key=lambda kw: kw.lower()) + [""])
     (Path(__file__).parent / "example-keywords.txt").write_text(found_kw)
 
 

doc/example-keywords.txt

@@ -2,6 +2,7 @@
 battery
 benchmarking
 burner-stabilized flame
+C++
 catalysis
 combustion
 compressible flow
@@ -11,12 +12,14 @@ electrochemistry
 equilibrium
 extinction
 flame speed
+Fortran 77
+Fortran 90
 fuel cell
 heat transfer
 ignition delay
-input files
 internal combustion engine
 kinetics
+Matlab
 mixture
 multicomponent transport
 multiphase
@@ -30,6 +33,7 @@ pollutant formation
 porous media
 preconditioner
 premixed flame
+Python
 radiative heat transfer
 reaction path analysis
 reactor network

doc/example-skip-keywords.txt

@@ -4,3 +4,4 @@ test_examples.m
 reactor_ode.m
 flame.m
 PFR_solver.m
+plotSolution.m

doc/sphinx/_static/custom.css

@@ -2,3 +2,9 @@ p + div.math {
     /* Remove post-paragraph space ahead of equation to center vertically */
     margin-top: -1.15em;
 }
+
+.sphx-glr-download-link-note {
+    /* Hide top-of-page note about download link at bottom */
+    display: none;
+    visibility: hidden;
+}

doc/sphinx/_templates/cantera-org-links.html

@@ -11,12 +11,6 @@
         </a>
     </li>
 
-    <li class="nav-item">
-        <a class="nav-link nav-internal" href="/examples/index.html">
-            Examples
-        </a>
-    </li>
-
     <li class="nav-item">
         <a class="nav-link nav-internal" href="/community.html">
             Community
@@ -29,12 +23,6 @@
         </a>
     </li>
 
-    <li class="nav-item current active">
-        <a class="nav-link nav-internal" href="/documentation/index.html">
-            Documentation
-        </a>
-    </li>
-
     <li class="nav-item">
         <a class="nav-link nav-internal" href="/blog/index.html">
             Blog