[FEATURE] Allow finer logging filtering (follow-up of #10219)

This is a follow-up of #10219. The purpose of this proposal is to formally define a mechanism for suppressing logging messages from third-party extensions assuming they use the Sphinx logging mechanism. In particular, we work under the following assumptions:

• Extensions declare a top-level logger using logging.getLogger(__name__) where logging is the sphinx.util.logging module.
• Extensions that do not use this logging mechanism but create loggers using logging.getLogger(__name__) with logging being the standard module will not be supported by the related PR.

I personally developed some extension to suppress messages from third-party extensions (or even built-in extensions), e.g., sphinx.ext.intersphinx which warnss users when an HTTP connection fails (I only want to suppress specific messages and not all warnings from sphinx.ext.intersphinx). The reason why I did this is because I work half of the time offline, meaning I don't have any Internet access. So, obviously, I get some warnings and that bothers me (and I don't want to update my conf.py everytime by swapping which inventory to query in priority). Anyway, that's for the rationale behind this issue, so here is the plan I suggest.

• Use the logging.Filter interface to intercept records that need to be filtered.

• Filters can be created by the user (and directly added to the workflow) or they can be configured using the following syntax in conf.py.

• The idea is to allow users to suppress messages:

  • by their emitting logger,
  • by their logging level,
  • by matching the logger's name with a regular expression,
  • by matching their content with a regular expression.

  The above filters should be composable, namely, one can suppress a specific message emitted with a specific level by a specific logger, or any message matching some regular expression, etc. That way, users can completely customize how to interact with third-party extensions. Note that using type and subtype is not always sufficient since some messages may be to generic (and in the end, the user has not control over the third-party extensions implementations unless they request them to always use type and subtype when logging messages).

• The loggers are then modified in place by adding the created filters. When loading an extension, Sphinx imports the corresponding (hence executing it). The idea is to apply the logging filtering mechanism as the "last" extension by simply inspecting the modules of each loaded extensions, searching for instances of SphinxLoggerAdapter and modify them accordingly.

Related

• #8845

Start by reading the linked follow-up issue #10219 and the Sphinx logging mechanism referenced in the proposal. Review how conf.py, SphinxLoggerAdapter, and loaded extensions participate in logging, then define the filter configuration and application points. Done means users can compose filters by logger, level, logger-name regex, and message regex without affecting unsupported standard loggers.