Consider documenting syntax errors

[ntBre]

One reason why we might want to have different error codes for different syntax errors is so that we can provide more detailed documentation for some syntax errors. This isn't much of a concern with the specific syntax error that @ntBre is adding here, as there's not much more to say than "you can't use the match statement on Python <3.10".¹. However, as we discussed on Brent's design proposal, it will be a concern with other syntax errors that we'll want to detect in the future -- for example, we have very nice docs for F404 currently in Ruff, and it would be a shame to provide worse docs for red-knot users when we start detecting that syntax error in our brand new tool.

Some errors that we may want to provide per-error docs for are errors that only appear on older or newer Python versions. For example, the details around when you're able to parenthesize context managers on Python <3.9 are pretty subtle. So are the details on when match patterns are considered irrefutable (it's a syntax error to have more than one irrefutable pattern in a match statement on Python 3.10+).

@MichaReiser also pointed out in the comments on Brent's design doc that there are existing syntax errors the parser detects that probably might also benefit from better docs.

(To be clear, I'm not saying that we have to have multiple error codes for these syntax errors. And there are obviously costs as well as benefits, which Micha outlined well. But this is one possible motivation for why it might help to have different error codes for different syntax errors: it would allow users to easily look them up in our documentation.)

Originally posted by @AlexWaygood in #16090 (comment)

Footnotes

1. That said, I actually don't think it would hurt to have a documentation page that links to the relevant PEPs that introduced the match statement, and/or the Python docs for the match statement. ↩

[AlexWaygood]

Thanks for opening the tracking issue! As I said in #16090 (comment), it's pretty important for me that we figure out a way to provide good documentation for the more complex errors you'll be tackling in this project, as it can sometimes be pretty subtle when and why something is a syntax error. I don't think we should stabilise these new errors before we have solid docs for the more complicated ones.