Sphinx argparse

.github/workflows/main.yml

@@ -327,7 +327,7 @@ jobs:
         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
+          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
       - name: Ensure 'scons help' options work

doc/sphinx/conf.py

@@ -39,6 +39,7 @@
               'sphinx.ext.autodoc',
               'sphinx.ext.todo',
               'sphinx.ext.autosummary',
+              'sphinxarg.ext',
               'sphinxcontrib.doxylink',
               'sphinx.ext.intersphinx',
               ]

doc/sphinx/cython/ck_conversion.rst

@@ -0,0 +1,11 @@
+**************************
+Chemkin to YAML conversion
+**************************
+
+For documentation and tutorial, refer to the `Converting Chemkin-format files
+<https://cantera.org/tutorials/ck2yaml-tutorial.html>`_ pages.
+
+Module-level documentation
+==========================
+
+.. automodule:: cantera.ck2yaml

doc/sphinx/cython/cti_conversion.rst

@@ -0,0 +1,12 @@
+***********************
+CTI to YAML conversion
+***********************
+
+For documentation of the command line interface, see the :ref:`cti2yaml <sec-cti2yaml>`
+section. For a tutorial, refer to the `Converting CTI and XML input files to YAML
+<https://cantera.org/tutorials/legacy2yaml.html>`_ pages.
+
+Module-level documentation
+==========================
+
+.. automodule:: cantera.cti2yaml

doc/sphinx/yaml/ctml_conversion.rst → doc/sphinx/cython/ctml_conversion.rst

@@ -2,6 +2,14 @@
 CTML to YAML conversion
 ***********************
 
+For documentation of the command line interface, see the :ref:`cml2yaml <sec-ctml2yaml>`
+section. For a tutorial, refer to the `Converting CTI and XML input files to YAML
+<https://cantera.org/tutorials/legacy2yaml.html>`_ pages.
+
+
+Module-level documentation
+==========================
+
 .. py:module:: cantera.ctml2yaml
 .. py:currentmodule:: cantera.ctml2yaml
 
@@ -16,7 +24,7 @@ processed, while `convert` takes an input filename or a string containing the CT
 to be converted, and optionally the name of the output file.
 
 Module-level functions
-======================
+----------------------
 
 .. autofunction:: float2string
 .. autofunction:: represent_float
@@ -30,7 +38,7 @@ Module-level functions
 .. autofunction:: main
 
 Conversion classes
-==================
+------------------
 
 .. autoclass:: Phase
    :no-undoc-members:
@@ -44,7 +52,7 @@ Conversion classes
    :no-undoc-members:
 
 Exceptions
-==========
+----------
 
 .. autoexception:: MissingXMLNode
 .. autoexception:: MissingXMLAttribute

doc/sphinx/cython/index.rst

@@ -17,3 +17,4 @@ Contents:
    constants
    units
    utilities
+   scripts

doc/sphinx/cython/scripts.rst

@@ -0,0 +1,14 @@
+.. _sec-converter-documentation:
+
+Mechanism Conversion
+====================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   ck_conversion
+   cti_conversion
+   ctml_conversion
+   yaml_conversion

doc/sphinx/cython/yaml_conversion.rst

@@ -0,0 +1,10 @@
+**************************
+YAML to Chemkin conversion
+**************************
+
+For documentation of the command line interface, see :ref:`sec-yaml2ck`.
+
+Module-level documentation
+==========================
+
+.. automodule:: cantera.yaml2ck

doc/sphinx/yaml/ck2yaml.rst

@@ -0,0 +1,7 @@
+**************************
+Chemkin to YAML conversion
+**************************
+
+.. note::
+    For documentation and tutorial, refer to the `Converting Chemkin-format files
+    <https://cantera.org/tutorials/ck2yaml-tutorial.html>`_ pages.

doc/sphinx/yaml/cti2yaml.rst

@@ -0,0 +1,14 @@
+.. _sec-cti2yaml:
+
+***********************
+CTI to YAML conversion
+***********************
+
+.. note::
+    For a tutorial, refer to the `Converting CTI and XML input files to YAML
+    <https://cantera.org/tutorials/legacy2yaml.html>`_ pages.
+
+.. argparse::
+   :module: cantera.cti2yaml
+   :func: create_argparser
+   :prog: cti2yaml

doc/sphinx/yaml/ctml2yaml.rst

@@ -0,0 +1,14 @@
+.. _sec-ctml2yaml:
+
+***********************
+CTML to YAML conversion
+***********************
+
+.. note::
+    For a tutorial, refer to the `Converting CTI and XML input files to YAML
+    <https://cantera.org/tutorials/legacy2yaml.html>`_ pages.
+
+.. argparse::
+   :module: cantera.ctml2yaml
+   :func: create_argparser
+   :prog: ctml2yaml

doc/sphinx/yaml/index.rst

@@ -11,6 +11,7 @@ YAML Input File Reference
    elements
    species
    reactions
-   cti_conversion
-   ctml_conversion
-   ck_conversion
+   ck2yaml
+   cti2yaml
+   ctml2yaml
+   yaml2ck

doc/sphinx/yaml/yaml2ck.rst

@@ -0,0 +1,10 @@
+.. _sec-yaml2ck:
+
+**************************
+YAML to Chemkin conversion
+**************************
+
+.. argparse::
+   :module: cantera.yaml2ck
+   :func: create_argparser
+   :prog: yaml2ck

interfaces/cython/cantera/ck2yaml.py

@@ -111,7 +111,6 @@
         return repr(data)
 
 def represent_float(self, data):
-    # type: (Any) -> Any
     if data != data:
         value = '.nan'
     elif data == self.inf_value:
@@ -2217,8 +2216,9 @@
 
     if '--id' in options:
         phase_name = options.get('--id', 'gas')
-        logger.warning("\nFutureWarning: "
-                       "Option '--id=...' will be replaced by '--name=...'")
+        logger.warning("\nDeprecationWarning: "
+                       "Option '--id=...' is replaced by '--name=...' and will be "
+                       "removed after Cantera 3.0.\n")
     else:
         phase_name = options.get('--name', 'gas')
 

interfaces/cython/cantera/cti2yaml.py

@@ -1720,8 +1720,10 @@
     return len(_species), len(_reactions), surfaces, output_name
 
 
-def main():
-    """Parse command line arguments and pass them to `convert`."""
+def create_argparser():
+    """
+    Create argparse parser
+    """
     parser = argparse.ArgumentParser(
         description=(
             "Convert legacy CTI input files to YAML format, where the first contiguous "
@@ -1743,6 +1745,12 @@
         "--no-validate", action="store_true", default=False,
         help="Skip validation step.")
 
+    return parser
+
+
+def main():
+    """Parse command line arguments and pass them to `convert`."""
+    parser = create_argparser()
     if len(sys.argv) not in [2, 3, 4, 5]:
         if len(sys.argv) > 5:
             print(

interfaces/cython/cantera/ctml2yaml.py

@@ -2652,8 +2652,10 @@
             emitter.dump(output_reactions, output_file)
 
 
-def main():
-    """Parse command line arguments and pass them to `convert`."""
+def create_argparser():
+    """
+    Create argparse parser
+    """
     parser = argparse.ArgumentParser(
         description="Convert legacy CTML input files to YAML format",
         epilog=(
@@ -2664,6 +2666,13 @@
     )
     parser.add_argument("input", help="The input CTML filename. Must be specified.")
     parser.add_argument("output", nargs="?", help="The output YAML filename. Optional.")
+
+    return parser
+
+
+def main():
+    """Parse command line arguments and pass them to `convert`."""
+    parser = create_argparser()
     if len(sys.argv) not in [2, 3]:
         if len(sys.argv) > 3:
             print(

interfaces/cython/cantera/yaml2ck.py

@@ -717,13 +717,10 @@
     return output_files
 
 
-def main():
+def create_argparser():
     """
-    Parse command line arguments and pass them to `convert`
-
-    .. versionadded:: 3.0
+    Create argparse parser
     """
-
     parser = argparse.ArgumentParser(
         description="Convert Cantera YAML input files to Chemkin-format mechanisms",
     )
@@ -795,7 +792,16 @@
         default=True,
         help="Check that the mechanism can be loaded back into Cantera.",
     )
+    return parser
+
 
+def main():
+    """
+    Parse command line arguments and pass them to `convert`
+
+    .. versionadded:: 3.0
+    """
+    parser = create_argparser()
     args = parser.parse_args()
 
     output_paths = convert(