I think switching this to DeprecationWarning would be better.

Using raise DeprecationWarning(...) has the effect of also printing out the stack trace, which most users are not interested in and I think has the effect of causing people to miss the actual important warning text, e.g.:

Traceback (most recent call last):
  File "/home/speth/src/cantera/interfaces/cython/cantera/ctml_writer.py", line 2772, in <module>
    main()
  File "/home/speth/src/cantera/interfaces/cython/cantera/ctml_writer.py", line 2764, in main
    raise DeprecationWarning("WARNING: The CTI and XML input file formats are deprecated and will be\n"
DeprecationWarning: WARNING: The CTI and XML input file formats are deprecated and will be
removed in Cantera 3.0. Use `cti2yaml.py` to convert CTI input files to
the YAML format. See https://cantera.org/tutorials/legacy2yaml.html for
more information.

I don't think you need to raise the DeprecatuonWarning. I think importing warnings and using that interface would be better. https://docs.python.org/3/library/warnings.html#warnings.warn

Perhaps FutureWarning would be better, too: https://docs.python.org/3/library/exceptions.html#FutureWarning

I see, I was misunderstanding how DeprecationWarning is supposed to be used, based on the fact that it is a type of Exception. But the output from warnings.warn still seems clunkier than I'd prefer:

/home/speth/src/cantera/build/python/cantera/ctml_writer.py:2765: FutureWarning: 
The CTI and XML input file formats are deprecated and will be
removed in Cantera 3.0. Use `cti2yaml.py` to convert CTI input files to
the YAML format. See https://cantera.org/tutorials/legacy2yaml.html for
more information.
  warnings.warn(

The line reference makes sense, but I don't really get why it prints the line of code that starts the call to warnings.warn (which, if the message were shorter, would just be repeating the message again).

Looks like the recommendation in the docs is to replace warnings.formatwarning (via SO). Something like

def custom_formatwarnings(msg, category, filename, lineno, line=None):
    return f"{filename}:{lineno}:{msg}\n"
warnings.formatwarning = custom_formatwarnings

Since the message is longer though, it doesn't bother me too much.

I don't understand what is "better" about using the warnings interface when:

• This message is triggered only when this file is called as a script (i.e., through the main method), so there's no benefit/opportunity for anything to interact with settings that would either suppress this warning or elevate it into an error
• All other warning output from this script is just handled by print anyway
• The entire script is deprecated and I'm planning deleting it as soon as we release Cantera 2.6.

Sounds good to me!

Should these be regular single quotes rather than back-ticks? (Here and elsewhere)

On a separate note, would it make sense to promote the legacy2yaml page to a more prominent position on the tutorials page (right now it's within the input-files sub-category)?

I'm starting to wondering if a large chunk of the "Input" documentation needs to be promoted a level in the website -- Right now, it's all buried as a subsection under "tutorials", which has the effect of both putting the input file related tutorials and extra layer deep, and hiding the YAML format documentation inside the tutorials section, which isn't really correct.

Actually, I take that back - Besides being accessible from within the "Tutorials" section, the general YAML documentation is available from the main cantera.org page under Documentation -> YAML Input File Users' Guide, and the documentation for specific models is available as Documentation -> YAML Input File API Reference, which seems about right.

I'm not sure how much more prominent the legacy2yaml page needs to be. Within the tutorials section, I think it's in the right place, though I suppose it could come before the deprecated options of "creating a new CTI file" and "conversion from Chemkin to CTI". For users who don't think they need tutorials, an additional link on the "Documentation" page wouldn't hurt either.

I personally think that the input format description should be linked on the main page. It’s tangential here, and the url in the warnings is fine

Sounds good to me!