Migrate compilation docs into Sphinx/MyST

.github/workflows/main.yml

@@ -338,11 +338,6 @@ 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/doc

SConstruct

@@ -935,6 +935,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 *
@@ -162,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

doc/sphinx/conf.py

@@ -222,7 +222,7 @@ def escape_splats(app, what, name, obj, options, lines):
     'pint': ('https://pint.readthedocs.io/en/stable/', None),
 }
 
-myst_enable_extensions = ["dollarmath", "amsmath", "deflist"]
+myst_enable_extensions = ["dollarmath", "amsmath", "deflist", "colon_fence"]
 
 # Ensure that the primary domain is the Python domain, since we've added the
 # MATLAB domain with sphinxcontrib.matlab