Use a warning subtype for Pygments unknown lexers

[b-kamphorst]

Is your feature request related to a problem? Please describe.
I'd like to suppress Pygments warnings indicating unkown lexer names:

WARNING: Pygments lexer name 'csv' is not known

Describe the solution you'd like
Add a type.subtype to the warning raised at https://github.com/sphinx-doc/sphinx/blob/v8.1.3/sphinx/highlighting.py#L167, similar to #3185.

Describe alternatives you've considered

Additional context

[AA-Turner]

I'd like to suppress Pygments warnings indicating unkown lexer names

What's the justification for this? If Pygments does not support the lexer, there is no real point listing it as the argument to .. code-block::, it just means "none" or "text". The relevant issue is pygments/pygments#1952.

A

[b-kamphorst]

I agree that there is no point listing it, but some people do (unaware that it has no added value). I'm including historical files from others (READMEs from previous versions) that have such "lexers".

The reason they got away with it is that, as you mention, such blocks are handled as text or none. It is a choice for the parser to complain about this. For example, our previous parser accepted them without warnings. I am happy with the warning as it helps us to write better documentation. However, my key point is that they can be parsed and in those cases the outcome is well defined. Sphinx has no issues parsing them into nice and expected html. So it should be acceptable to parse files that contain code blocks with incorrect lexers. Do we agree on this?

If we agree that such files and lexers are acceptable and can be parsed with well-defined behaviour, then I would argue that a warning code in order to suppress those warnings is justified.

For my particular use case, I would like to parse historical documentation while suppressing this warning (and failing on other warnings that indicate e.g. missing images or files that I can and should solve).

(Note: I'm not advocating that there should be a CSV lexer.)

Does this make sense? And would you agree, or is there some point in this reasoning that you are uncomfortable with?

[b-kamphorst]

I just thought of an example that might be helpful. I also use the myst_parser, which warns me for non-consecutive headers in my markdown files. Is it elegant to have non-consecutive headers? No. Should we educate the user? Yes. Is it sufficiently severe that a user shouldn't be able to suppress this warning? No, see myst.header type..

I fully acknowledge that extensions make their own choices and that those are independent from the Sphinx core choices, so this is for illustrative purposes only. I just wanted to say that I feel that the use cases are similar, and their line of reasoning could be applied here as well.