Suppress mock object warnings from autodoc

[sdhiscocks]

Is your feature request related to a problem? Please describe.
When building with warnings as errors (-W flag), mock objects cause build failure (for example below).

WARNING: A mocked object is detected: 'example.mock.object'

This occurs with class attributes, or enum members, pointing to mock objects, even if they are documented with #:, which produce valid documentation.

Describe the solution you'd like
As suggested in #9631, it would be useful to have a subtype on the warning (e.g. mock_objects) so these warnings can be ignored.

Describe alternatives you've considered
Suppressing all autodoc warnings works, but this isn't ideal.

Additional context

• New mock warning in Sphinx 4.2.0 breaks strict builds #9631

[tk0miya]

I think the warnings should not be emitted if the mocked object can produce valid docs. I think it's a bug of autodoc that emits incorrect warnings. So I don't think it's better to suppress them.

Could you share an example to reproduce the warning? I'll try to fix it.

[sdhiscocks]

So issue we've seen is with this Enum we have defined, where the enum name points to a (mocked) function. The Enum documentation looks fine despite the warning.

We have a recent build on CircleCI which got caught on this warning, but no issues with documentation it produced.

[tk0miya]

Thank you for example. I understand what happened. The enum subclass provides _generate_next_value_() method that generates value from tensornets module (it's mocked!) for enum.auto(). I also reproduced.

Note: Dockefile to reproduce the error:

FROM python:3.8-slim

RUN apt update; apt install -y build-essential curl git unzip vim
RUN git clone https://github.com/dstl/Stone-Soup
WORKDIR Stone-Soup
RUN pip install -e .[dev]
WORKDIR /Stone-Soup/docs
RUN make HTML