Improve user guidance for ck2cti / ck2yaml warnings and errors

[ischoegl]

Abstract/Motivation

There are frequent requests about conversion warnings on the user group (most of which can be addressed/suppressed by the --permissive flag). While users are already directed to the website for more information, i.e.

Please check https://cantera.org/tutorials/ck2yaml-tutorial.html#debugging-common-errors-in-ck-files
for the correct Chemkin syntax.

it may make sense to specifically guiding users to this option.

As a comment, the link provided to users directs to a section that - at least on my browser - starts below the portion with the essential information needed (which is just above the #debugging-common-errors-in-ck-files section)

References

Recurring questions on the UG.

[speth]

I wonder if it would help if the actual exception message was more clearly clearly separated from the traceback, or if the traceback was not even shown by default. I get the feeling a lot of users see a wall of code that they don't understand, ignore it, and post to the UG without noticing that there is a relatively nice, human readable, and actionable message buried in there.

You're right that the link is to the heading just below the description of the --permissive option. I guess that's a little awkward, since the things allowed by --permissive may or may not be considered errors. The message linking to this specific heading is generic and output by any error in ck2yaml, regardless of whether the --permissive flag is a workaround.

[ischoegl]

I get the feeling a lot of users see a wall of code that they don't understand, ignore it, and post to the UG without noticing that there is a relatively nice, human readable, and actionable message buried in there.

Exactly my take on this.

[bryanwweber]

I wonder if we used the logging module if we could avoid raising exceptions, but still provide error messages to users. This would also make it easy to process the entire file and exit with an error code at the end, rather than stopping on the first error.

[ischoegl]

:+1: on logging.

[ischoegl]

However, as a short-term fix, it may make sense to add a note at the beginning of the section below the section header, as more often than not, debugging of CK input is not needed to address issues.

[speth]

I think you still have to stop after the first error in many cases, though perhaps not this one. Any time you decide not to raise InputError, you have to decide what to do instead.

We're already using the logging module in ck2yaml for non-fatal warnings, so that's nothing new.

[ischoegl]

While I believe there is more to this topic, at least the paragraph on the website is easy to move, see Cantera/cantera-website#141

[bryanwweber]

@ischoegl is this issue complete? I'm not sure what else should be done here.

[ischoegl]

I don’t think it’s completely resolved. I’d prefer if it were left open.

[bryanwweber]

I don’t think it’s completely resolved. I’d prefer if it were left open.

Can you clarify what you see as being left to do here?

[ischoegl]

Looked at this again and believe this is probably fine.