Website structure update

.github/workflows/main.yml

@@ -323,10 +323,10 @@ jobs:
         run: python3 -m pip install -U pip setuptools wheel
       - name: Install Python dependencies
         run: |
-          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 ruamel.yaml scons numpy cython 'sphinx>=5.3.0' \
+            sphinxcontrib-matlabdomain sphinxcontrib-doxylink sphinxcontrib-bibtex \
+            pydata-sphinx-theme==0.14.1 sphinx-argparse sphinx_design myst-nb \
+            sphinx-copybutton matplotlib pandas scipy pint
           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
@@ -338,20 +338,15 @@ jobs:
           python3 `which scons` help --options
           python3 `which scons` help --list-options
           python3 `which scons` help --option=prefix
-      - name: Parse configuration options from SConstruct as reST
-        run: |
-          python3 `which scons` help --restructured-text --dev --output=config-options-dev.rst
-          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 doc
+          cd build/doc
+          tar --exclude="*.map" --exclude="*.md5" -czf docs.tar.gz html
         if: failure() || success()
       - name: Store archive of docs output
         uses: actions/upload-artifact@v3
         with:
-          path: build/docs.tar.gz
+          path: build/doc/docs.tar.gz
           name: docs
           retention-days: 14
         if: failure() || success()
@@ -369,12 +364,12 @@ jobs:
         env:
           RSYNC_USER: "ctdeploy"
           RSYNC_SERVER: "cantera.org"
-          RSYNC_DEST: "cantera/documentation/dev"
-          DOCS_OUTPUT_DIR: "./build/doc/"
+          RSYNC_DEST: "cantera/dev"
+          DOCS_OUTPUT_DIR: "./build/doc/html/"
         run: |
           rsync -avzP --checksum --exclude='*.map' --exclude='*.md5' \
-          --exclude='/doxygen/xml' --delete --delete-excluded \
-          "${DOCS_OUTPUT_DIR}" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST}
+            --delete --delete-excluded --filter='P .htaccess' \
+            "${DOCS_OUTPUT_DIR}" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST}
 
   run-examples:
     name: Run Python ${{ matrix.python-version }} examples on ${{ matrix.os }}

SConstruct

@@ -937,6 +937,11 @@ for arg in ARGUMENTS:
         logger.error(f"Encountered unexpected command line option: {arg!r}")
         sys.exit(1)
 
+# Store full config for doc build
+if env['sphinx_docs']:
+    config.add(windows_options)
+    env['config'] = config
+
 env["cantera_version"] = "3.1.0a1"
 # For use where pre-release tags are not permitted (MSI, sonames)
 env['cantera_pure_version'] = re.match(r'(\d+\.\d+\.\d+)', env['cantera_version']).group(0)

doc/SConscript

@@ -1,6 +1,7 @@
 
 from collections import namedtuple
 from os.path import join as pjoin
+from pathlib import Path
 import os
 import subprocess
 from buildutils import *
@@ -96,25 +97,30 @@ def get_function_name(function_string):
     else:
         return sig
 
-if localenv['doxygen_docs']:
-    docs = build(localenv.Command('#build/doc/doxygen/html/index.html',
-                                  'doxygen/Doxyfile', 'doxygen $SOURCE'))
+if localenv['doxygen_docs'] or localenv['sphinx_docs']:
+    docs = build(localenv.Command(
+        '#build/doc/html/cxx/index.html', 'doxygen/Doxyfile',
+        [
+            Delete("build/doc/html/cxx"),
+            'doxygen $SOURCE',
+            Copy("build/doc/html/cxx", "build/doc/doxygen/html")
+        ]
+    ))
     env.Depends(docs, env.Glob('#doc/doxygen/*') +
                       multi_glob(env, '#include/cantera', 'h') +
                       multi_glob(env, '#include/cantera/*', 'h') +
                       multi_glob(env, '#src/cantera/*', 'h', 'cpp'))
 
     env.Alias('doxygen', docs)
-    install(localenv.RecursiveInstall, '$inst_docdir/doxygen/html',
-            '#/build/doc/doxygen/html', exclude=['\\.map', '\\.md5'])
 
 if localenv['sphinx_docs']:
+    localenv.PrependENVPath('PYTHONPATH', Dir('#build/python').abspath)
     def build_sphinx(target, source, env):
         cmd = [env['sphinx_cmd']] + env['sphinx_options'].split()
         if env['logging'] == 'debug':
             cmd.append('-v')
         cmd += ('-b', 'html', '-d', 'build/doc/sphinx/doctrees', 'build/doc/sphinx',
-                'build/doc/sphinx/html')
+                'build/doc/html')
         code = subprocess.call(cmd, env=env['ENV'])
         if code:
             raise Errors.BuildError(target, action=env['sphinx_cmd'])
@@ -157,6 +163,16 @@ if localenv['sphinx_docs']:
                     localenv.Command(f"#build/doc/samples/clib/{clib_file.name}",
                                      clib_file, Copy("$TARGET", "$SOURCE")))
 
+    # Generate documentation for SCons configuration options
+    def save_config(target, source, env):
+        Path(str(target[0])).parent.mkdir(parents=True, exist_ok=True)
+        with open(str(target[0]), "w") as outfile:
+            outfile.write(env["config"].to_rest())
+    scons_opts = localenv.Command(
+        "#build/doc/sphinx/develop/compiling/scons-config-options.rst.inc",
+        "#SConstruct", save_config)
+    env.Depends(sphinxdocs, scons_opts)
+
     # 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
@@ -251,5 +267,5 @@ if localenv['sphinx_docs']:
     localenv.AlwaysBuild(sphinxdocs)
     if localenv['doxygen_docs']:
         localenv.Depends(sphinxdocs, docs)
-    install(localenv.RecursiveInstall, '$inst_docdir/sphinx/html',
-            '#build/doc/sphinx/html')
+    install(localenv.RecursiveInstall, '$inst_docdir/html',
+            '#build/doc/html', exclude=['\\.map', '\\.md5'])

doc/doxygen/Doxyfile

@@ -1213,7 +1213,8 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  = ext/doxygen-awesome-css/doxygen-awesome.css
+HTML_EXTRA_STYLESHEET  = ext/doxygen-awesome-css/doxygen-awesome.css \
+                         doc/doxygen/cantera-doxygen.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note

doc/doxygen/cantera-doxygen.css

@@ -0,0 +1,39 @@
+/* Colors to match pydata-sphinx-theme */
+html {
+    --primary-color: rgb(10, 125, 145);
+    --pst-color-text-muted: rgb(100, 100, 100);
+}
+
+html.dark-mode {
+    --primary-color: rgb(63, 177, 197);
+    --pst-color-text-muted: rgb(164, 164, 164);
+}
+
+ul#main-menu li a {
+    /* Hide Doxygen navigation tabs that are duplicated in the sidebar */
+    visibility: hidden;
+    display: none !important;
+}
+
+div#top {
+    /* Fix alignment of nav tabs added using header.html */
+    justify-content: left;
+}
+
+/* Re-style the nav bar links to approximate pydata-sphinx-theme */
+.sm-dox a {
+    color: var(--pst-color-text-muted) !important;
+    font-size: 16px;
+    padding: 0 8px;
+}
+
+.sm-dox a#selected {
+    color: var(--primary-color) !important;
+    font-weight: bold;
+}
+
+.sm-dox a:hover {
+    background: unset;
+    color: var(--primary-color) !important;
+    font-size: 16px;
+}

doc/doxygen/cantera.bib

@@ -364,8 +364,7 @@ @article{sengers1986
     volume = {15},
     url = {https://dx.doi.org/10.1063/1.555763},
     year = {1986},
-    %doi = {10.1063/1.555763},
-    }
+    doi = {10.1063/1.555763}}
 @article{silvester1977,
     author = {L.~F.~Silvester and K.~S.~Pitzer},
     title = {Thermodynamics of electrolytes. 8. High-temperature properties, including
@@ -383,6 +382,13 @@ @book{smith1982
     isbn = {978-0471093473},
     title = {Chemical Reaction Equilibrium Analysis: Theory and Algorithms},
     year = {1982}}
+@online{smith1999,
+    title = {{GRI-Mech} 3.0},
+    author = {G.~P.~Smith and D.~M.~Golden and M.~Frenklach and N~.W.~Moriarty and
+        B.~Eiteneer and M.~Goldenberg and C.~T.~Bowman and R.~K.~Hanson and S.~Song
+        and W.~C.~Gardiner, Jr. and V.~V.~Lissianski and Z.~Qin},
+    url = {http://combustion.berkeley.edu/gri-mech/version30/text30.html},
+    year = {1999}}
 @article{stewart1989,
     author = {P.~H.~Stewart and C.~W.~Larson and D.~Golden},
     journal = {Combustion and Flame},

doc/doxygen/header.html

@@ -8,6 +8,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
 <!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<link rel="shortcut icon" href="$relpath^../_static/images/favicon.png">
 <link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="$relpath^jquery.js"></script>
 <script type="text/javascript" src="$relpath^dynsections.js"></script>
@@ -69,5 +70,15 @@
  </tbody>
 </table>
 </div>
+<div>
+  <ul class="sm sm-dox" style="display: block;">
+    <li><a href="$relpath^../install/index.html">Install</a></li>
+    <li><a href="$relpath^../userguide/index.html">User Guide</a></li>
+    <li><a href="$relpath^../examples/index.html">Examples</a></li>
+    <li><a id="selected" href="$relpath^../reference/index.html">Reference</a></li>
+    <li><a href="$relpath^../develop/index.html">Develop</a></li>
+    <li><a href="/community.html">Community</a></li>
+  </ul>
+</div>
 <!--END TITLEAREA-->
 <!-- end header part -->

doc/sphinx/_static/custom.css

@@ -1,3 +1,7 @@
+html {
+    --pst-icon-external-link: "";
+}
+
 p + div.math {
     /* Remove post-paragraph space ahead of equation to center vertically */
     margin-top: -1.15em;
@@ -8,3 +12,23 @@ p + div.math {
     display: none;
     visibility: hidden;
 }
+
+/* Make extra room for header section links when page isn't wide enough */
+@media(max-width: 1199.88px) {
+    /* Collapse search field to just a button */
+    button.search-button-field .search-button__default-text {
+        display: none;
+        visibility: hidden;
+    }
+    .search-button-field > :not(svg) {
+        display: none;
+        visibility: hidden;
+    }
+
+    /* Hide text portion of the Cantera logo */
+    .navbar-brand img {
+        width: 36px;
+        object-fit: cover;
+        object-position: left
+    }
+}

doc/sphinx/_static/doc-versions.json

@@ -2,7 +2,7 @@
     {
         "name": "3.1 (dev)",
         "version": "3.1",
-        "url": "/documentation/dev/sphinx/html/"
+        "url": "/dev/"
     },
     {
         "name": "3.0.0 (stable)",

doc/sphinx/_templates/numfocus.html

@@ -1,4 +1,6 @@
 <div id="numfocus">
-<a href="https://numfocus.salsalabs.org/donate-to-cantera/index.html" class="btn btn-secondary" type="button">Donate to Cantera</a>
+<a href="https://numfocus.salsalabs.org/donate-to-cantera/index.html"
+   class="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary reference external"
+   type="button">Donate to Cantera</a>
 <a href="https://numfocus.org/"><img src="{{pathto("_static/images/powered_by_NumFOCUS.svg", 1) }}" border="0" alt="NumFOCUS"/></a>
 </div>