Show warnings with their "type" and "subtype"?

[mgeier]

Similar to #8813, just for warnings instead of exceptions:

Currently, warning messages are shown like this:

WARNING: Some warning message

If a warning can be disabled, I think it would be helpful to display the warning type and subtype, maybe like:

WARNING (some_type.some_subtype): Some warning message

[tk0miya]

-0: IMO, it's better to resolve the root reason for the warning instead of suppressing. I feel it's noisy...

[chrisjsewell]

+1

For myst-parser and myst-nb I have had numerous people ask to silence a specific warning.
Although I encourage them to fix the warning, it is true that some warnings are more important than others. Also, as already mentioned, displaying the warning type helps to identify its origin, and thus how to fix it.

Displaying warning types has plenty of precedence in other packages, such as:

• https://mypy.readthedocs.io/en/stable/error_codes.html?highlight=show#silencing-errors-based-on-error-codes
• http://pylint.pycqa.org/en/latest/user_guide/message-control.html#block-disables

In myst-parser I now append the warning type to the end of the message: https://myst-parser.readthedocs.io/en/latest/using/howto.html#suppress-warnings

WARNING: Non-consecutive header level increase; 1 to 3 [myst.header]

I feel it's noisy...

You could simply add a configuration option to control whether they are displayed, e.g. show_warning_type

Also to note, in https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings it says "Now, this option should be considered experimental.".
I assume this is no longer the case, since this option has been around for a long time now?

[chrisjsewell]

I would consider creating a PR, but obviously would want to know first it was not likely to be rejected 😬

[mgeier]

@tk0miya

IMO, it's better to resolve the root reason for the warning instead of suppressing.

I agree, most of the times it's better to fix the root reason.

But sometimes it's not, and then it would be nice to have the additional information in order to silence the right warnings.
If not, people might just silence all warnings, which might be worse!

So I would add to your argument:

• most of the time, it's better to resolve the root reason for the warning instead of suppressing
• if not, it's better to suppress only certain warnings explicitly instead of suppressing all of them

I feel it's noisy...

This would certainly add a little bit of noise, but I think it would be worth it.

For me, the main usage is in different CI tasks. I might run Sphinx in multiple CI tasks, but for certain builders (e.g. linkcheck) I might want to disable some warnings, which I want to keep enabled for the main html builder task.

Does this make sense?

@chrisjsewell

You could simply add a configuration option to control whether they are displayed, e.g. show_warning_type

This is certainly a possibility, but I feel that this would never actually be used (assuming it has the correct default value).

People who care about warning messages will keep them to a minimum (ideally 0) anyway. And people who don't care, won't care about the exact display of the warnings anyway.

[arwedus]

-0: IMO, it's better to resolve the root reason for the warning instead of suppressing. I feel it's noisy...

every C++ compiler gives an exact warning number, by which you can also disable the given warning type - if done right, the "noisiness" can be kept low and the output made really universal.

[felix-hilden]

@tk0miya I agree that it is better to fix the underlying issue. But to present another situation where it could be useful: I'm developing an extension that parses code blocks and links the code with corresponding autodoc entries. I intend to issue warnings when those entries are not found, but the code example might still be valid. So a user might want to ignore the warning because there's nothing they can do until the entry is added (perhaps in a 3rd party library). They can look at the extension documentation, but it would be much faster to see the exact warning type in the message.

It is a bit noisy though 😄 and I think more often it's a valid warning that can be fixed. So if not default behavior, could this at least be available via configuration?

[mara004]

I agree this would be useful, especially for working with myst. There are some references in my markdown files (in pypdfium2) that naturally can't be translated to Sphinx/rst. I'd like to suppress this noise to prevent me from overlooking real warnings.