Improve warning suppression

[julian-smith-artifex-com]

It looks like it is not possible to suppress some sphinx warnings, which makes it difficult to start to use sphinx-build --fail-on-warning in an existing Sphinx project.

For example WARNING: duplicate object description of ... other instance in ..., use :no-index: for one of them is generated in sphinx/domains/python/__init__.py:PythonDomain.note_object() with:

                logger.warning(
                    __(
                        'duplicate object description of %s, '
                        'other instance in %s, use :no-index: for one of them'
                    ),
                    name,
                    other.docname,
                    location=location,
                )

This does not specify <type> or <subtype> so we end up in sphinx/util/logging.py:def is_suppressed_warning() with type=None and subtype=None, so the warning is never suppressed.

I guess it would take a lot of effort to change all calls of logger.warning() to specify <type> and <subtype>.

So would it instead be feasible to allow suppression of warnings specified as regular expressions or callables that work on the warning text itself instead of <type> and <subtype>?

For example if we added a <record> arg to is_suppressed_warning() it could do:

def is_suppressed_warning(warning_type, sub_type, suppress_warnings, record):
    for suppression in suppressed_warnings:
        if callable(suppression)
            if suppression(record.msg):
                return True
        elif isinstance(suppression, re.Pattern):
            if re.match(suppression, record.msg):
                return True
        else:
            ... use existing code that checks whether string <subpression> matches <warning_type> and <subtype>.

Then conf.py could contain things like:

suppress_warnings = [
        'ref.any',
        'toc.not_included',
        'ref.ref',
        lambda text: text.startswith('duplicate object description of'),
        ]