diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 9de28c085d..6dff9919ad 100644 --- a/.github/workflows/main.yml +++ b/.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 diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index cbfc606da1..6e43679cb6 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -39,6 +39,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.autosummary', + 'sphinxarg.ext', 'sphinxcontrib.doxylink', 'sphinx.ext.intersphinx', ] diff --git a/doc/sphinx/cython/ck_conversion.rst b/doc/sphinx/cython/ck_conversion.rst new file mode 100644 index 0000000000..27aca26319 --- /dev/null +++ b/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 +`_ pages. + +Module-level documentation +========================== + +.. automodule:: cantera.ck2yaml diff --git a/doc/sphinx/cython/cti_conversion.rst b/doc/sphinx/cython/cti_conversion.rst new file mode 100644 index 0000000000..642062cc5c --- /dev/null +++ b/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 ` +section. For a tutorial, refer to the `Converting CTI and XML input files to YAML +`_ pages. + +Module-level documentation +========================== + +.. automodule:: cantera.cti2yaml diff --git a/doc/sphinx/yaml/ctml_conversion.rst b/doc/sphinx/cython/ctml_conversion.rst similarity index 82% rename from doc/sphinx/yaml/ctml_conversion.rst rename to doc/sphinx/cython/ctml_conversion.rst index b0b982a7af..5d43ac9cee 100644 --- a/doc/sphinx/yaml/ctml_conversion.rst +++ b/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 ` +section. For a tutorial, refer to the `Converting CTI and XML input files to YAML +`_ 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 diff --git a/doc/sphinx/cython/index.rst b/doc/sphinx/cython/index.rst index 25490f21ea..7b74fa17a4 100644 --- a/doc/sphinx/cython/index.rst +++ b/doc/sphinx/cython/index.rst @@ -17,3 +17,4 @@ Contents: constants units utilities + scripts diff --git a/doc/sphinx/cython/scripts.rst b/doc/sphinx/cython/scripts.rst new file mode 100644 index 0000000000..b014132afc --- /dev/null +++ b/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 diff --git a/doc/sphinx/cython/yaml_conversion.rst b/doc/sphinx/cython/yaml_conversion.rst new file mode 100644 index 0000000000..ffa976d866 --- /dev/null +++ b/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 diff --git a/doc/sphinx/yaml/ck2yaml.rst b/doc/sphinx/yaml/ck2yaml.rst new file mode 100644 index 0000000000..1f0a76b29e --- /dev/null +++ b/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 + `_ pages. diff --git a/doc/sphinx/yaml/ck_conversion.rst b/doc/sphinx/yaml/ck_conversion.rst deleted file mode 100644 index 8dda685ef9..0000000000 --- a/doc/sphinx/yaml/ck_conversion.rst +++ /dev/null @@ -1,5 +0,0 @@ -************************** -YAML to Chemkin conversion -************************** - -.. automodule:: cantera.yaml2ck diff --git a/doc/sphinx/yaml/cti2yaml.rst b/doc/sphinx/yaml/cti2yaml.rst new file mode 100644 index 0000000000..c8e842dc78 --- /dev/null +++ b/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 + `_ pages. + +.. argparse:: + :module: cantera.cti2yaml + :func: create_argparser + :prog: cti2yaml diff --git a/doc/sphinx/yaml/cti_conversion.rst b/doc/sphinx/yaml/cti_conversion.rst deleted file mode 100644 index cfb900cd8a..0000000000 --- a/doc/sphinx/yaml/cti_conversion.rst +++ /dev/null @@ -1,5 +0,0 @@ -*********************** -CTI to YAML conversion -*********************** - -.. automodule:: cantera.cti2yaml diff --git a/doc/sphinx/yaml/ctml2yaml.rst b/doc/sphinx/yaml/ctml2yaml.rst new file mode 100644 index 0000000000..4a638b262d --- /dev/null +++ b/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 + `_ pages. + +.. argparse:: + :module: cantera.ctml2yaml + :func: create_argparser + :prog: ctml2yaml diff --git a/doc/sphinx/yaml/index.rst b/doc/sphinx/yaml/index.rst index bf46fdabaf..6f2c91dfff 100644 --- a/doc/sphinx/yaml/index.rst +++ b/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 diff --git a/doc/sphinx/yaml/yaml2ck.rst b/doc/sphinx/yaml/yaml2ck.rst new file mode 100644 index 0000000000..51ed171344 --- /dev/null +++ b/doc/sphinx/yaml/yaml2ck.rst @@ -0,0 +1,10 @@ +.. _sec-yaml2ck: + +************************** +YAML to Chemkin conversion +************************** + +.. argparse:: + :module: cantera.yaml2ck + :func: create_argparser + :prog: yaml2ck diff --git a/interfaces/cython/cantera/ck2yaml.py b/interfaces/cython/cantera/ck2yaml.py index d802df0a8d..3a0fd143df 100644 --- a/interfaces/cython/cantera/ck2yaml.py +++ b/interfaces/cython/cantera/ck2yaml.py @@ -111,7 +111,6 @@ def float2string(data): 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 @@ def main(argv): 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') diff --git a/interfaces/cython/cantera/cti2yaml.py b/interfaces/cython/cantera/cti2yaml.py index 1963be042d..a42b2142bb 100644 --- a/interfaces/cython/cantera/cti2yaml.py +++ b/interfaces/cython/cantera/cti2yaml.py @@ -1720,8 +1720,10 @@ def convert(filename=None, output_name=None, text=None, encoding="latin-1"): 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 @@ def main(): "--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( diff --git a/interfaces/cython/cantera/ctml2yaml.py b/interfaces/cython/cantera/ctml2yaml.py index 2ab7636807..556141bda4 100644 --- a/interfaces/cython/cantera/ctml2yaml.py +++ b/interfaces/cython/cantera/ctml2yaml.py @@ -2652,8 +2652,10 @@ def convert( 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 @@ def main(): ) 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( diff --git a/interfaces/cython/cantera/yaml2ck.py b/interfaces/cython/cantera/yaml2ck.py index a21f8d0e4f..adf26f3d79 100644 --- a/interfaces/cython/cantera/yaml2ck.py +++ b/interfaces/cython/cantera/yaml2ck.py @@ -717,13 +717,10 @@ def convert( 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 @@ def main(): 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(