Cantera 3.0 website converter script documentation

[ischoegl]

Problem description

The documentation of the CLI scripts is confusing, i.e. cti2yaml, ctml2yaml and yaml2ck, while ck2yaml documentation is absent.

Example:

Rather than using the module-level documentation at the top level, it would be preferable to document arguments used from the command line interface. For Sphinx, there is the option to use the sphinx-argparse module, which generates documentation for CLI functions that are based on argparse (unfortunately this excludes ck2yaml).

While there is still an argument to be made for the inclusion of detailed documentation for "under-the-hood" functions used by the converter scripts, they probably should not appear at the top level in the left menu.

In terms of navigation, this becomes more apparent on the Sphinx index page ... the current documentation likely belongs into the "Python Module Documentation" instead of the "YAML Input File Reference".

[speth]

The primary user documentation for the ck2yaml, ctml2yaml, and cti2yaml scripts is based at /tutorials/input-files.html and the pages linked to from there.

I think you're right that this documentation of the internals of these conversion scripts is a bit too prominent, and the more relevant documentation to link to from the YAML section would be /tutorials/ck2yaml-tutorial.html and friends (though that suffers from the fragility of linking from the API docs back to pages on cantera-website).