Add script to convert CTML to YAML input format

SConstruct

@@ -59,6 +59,7 @@ if 'clean' in COMMAND_LINE_TARGETS:
     removeDirectory('build')
     removeDirectory('stage')
     removeDirectory('.sconf_temp')
+    removeDirectory('test/work')
     removeFile('.sconsign.dblite')
     removeFile('include/cantera/base/config.h')
     removeFile('src/pch/system.h.gch')
@@ -1199,7 +1200,7 @@ if env['VERBOSE']:
 env['python_cmd_esc'] = quoted(env['python_cmd'])
 
 # Python Package Settings
-python_min_version = LooseVersion('3.3')
+python_min_version = LooseVersion('3.5')
 cython_min_version = LooseVersion('0.23')
 numpy_min_test_version = LooseVersion('1.8.1')
 

doc/sphinx/conf.py

@@ -40,9 +40,10 @@
               'sphinx.ext.autosummary',
               'sphinxcontrib.doxylink',
               'sphinxcontrib.katex',  # Use KaTeX because it's faster and the main site uses it
+              'sphinx.ext.intersphinx',
               ]
 
-katex_version = '0.10.0-beta'
+katex_version = '0.11.1'
 
 autodoc_default_flags = ['members','show-inheritance','undoc-members']
 
@@ -53,6 +54,12 @@
                '../../doxygen/html/')
 }
 
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
+    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+}
+
 # Ensure that the primary domain is the Python domain, since we've added the
 # MATLAB domain with sphinxcontrib.matlab
 primary_domain = 'py'

doc/sphinx/yaml/ctml_conversion.rst

@@ -0,0 +1,51 @@
+***********************
+CTML to YAML conversion
+***********************
+
+.. py:module:: cantera.ctml2yaml
+.. py:currentmodule:: cantera.ctml2yaml
+
+The script ``ctml2yaml.py`` will convert files from the legacy CTML format to YAML input
+format. The documentation below describes the classes and functions in the script. Each
+function/method is annotated with the Python types that the function accepts.
+
+Most users will access the functionality of this module via the command line with the
+``ctml2yaml`` entry-point script. For programmatic access, the `main` and/or `convert`
+functions should be used. `main` should be used when command line arguments must be
+processed, while `convert` takes an input filename or a string containing the CTML file
+to be converted, and optionally the name of the output file.
+
+Module-level functions
+======================
+
+.. autofunction:: float2string
+.. autofunction:: represent_float
+.. autofunction:: get_float_or_quantity
+.. autofunction:: split_species_value_string
+.. autofunction:: clean_node_text
+.. autofunction:: create_species_from_data_node
+.. autofunction:: create_reactions_from_data_node
+.. autofunction:: create_phases_from_data_node
+.. autofunction:: convert
+.. autofunction:: main
+
+Conversion classes
+==================
+
+.. autoclass:: Phase
+   :no-undoc-members:
+.. autoclass:: Species
+   :no-undoc-members:
+.. autoclass:: SpeciesThermo
+   :no-undoc-members:
+.. autoclass:: SpeciesTransport
+   :no-undoc-members:
+.. autoclass:: Reaction
+   :no-undoc-members:
+
+Exceptions
+==========
+
+.. autoexception:: MissingXMLNode
+.. autoexception:: MissingXMLAttribute
+.. autoexception:: MissingNodeText

doc/sphinx/yaml/index.rst

@@ -11,3 +11,4 @@ YAML Input File Reference
    elements
    species
    reactions
+   ctml_conversion

interfaces/cython/cantera/cti2yaml.py

@@ -3,14 +3,12 @@
 # This file is part of Cantera. See License.txt in the top-level directory or
 # at https://cantera.org/license.txt for license and copyright information.
 
-"""
-cti2yaml.py: Convert legacy CTI input files to YAML
-
-Usage:
-    python cti2yaml.py mech.cti [out.yaml]
+"""Convert legacy CTI input files to YAML.
 
-This will produce the output file 'mech.yaml' if an output file name is not
-specified.
+There are two main entry points to this script, `main` and `convert`. The former is
+used from the command line interface and parses the arguments passed. The latter
+accepts either the name of the CTI input file or a string containing the CTI
+content.
 """
 
 import sys
@@ -19,6 +17,7 @@
 from collections import OrderedDict
 import numpy as np
 from email.utils import formatdate
+import argparse
 
 try:
     import ruamel_yaml as yaml
@@ -1669,13 +1668,33 @@ def convert(filename=None, output_name=None, text=None):
 
 
 def main():
-    if len(sys.argv) == 1  or sys.argv[1] in ('-h', '--help'):
-        print(__doc__)
-        sys.exit(0)
-    if len(sys.argv) not in (2,3):
-        raise ValueError("Incorrect number of command line arguments.\n"
-            "See 'cti2yaml --help' for more information.")
-    convert(*sys.argv[1:])
+    """Parse command line arguments and pass them to `convert`."""
+    parser = argparse.ArgumentParser(
+        description="Convert legacy CTI input files to YAML format",
+        epilog=("The 'output' argument is optional. If it is not given, an output "
+                "file with the same name as the input file is used, with the extension "
+                "changed to '.yaml'.")
+    )
+    parser.add_argument("input", help="The input CTI filename. Must be specified.")
+    parser.add_argument("output", nargs="?", help="The output YAML filename. Optional.")
+    if len(sys.argv) not in [2, 3]:
+        if len(sys.argv) > 3:
+            print(
+                "cti2yaml.py: error: unrecognized arguments:",
+                ' '.join(sys.argv[3:]),
+                file=sys.stderr,
+            )
+        parser.print_help(sys.stderr)
+        sys.exit(1)
+    args = parser.parse_args()
+    input_file = pathlib.Path(args.input)
+    if args.output is None:
+        output_file = input_file.with_suffix(".yaml")
+    else:
+        output_file = pathlib.Path(args.output)
+
+    convert(input_file, output_file)
+
 
 if __name__ == "__main__":
     main()