New mock warning in Sphinx 4.2.0 breaks strict builds

[peterjc]

Describe the bug

Upgraded from Sphinx 4.1.2 to 4.2.0, build fails due to #9507

Success with 4.1.2,

https://app.circleci.com/pipelines/github/biopython/biopython/473/workflows/40320ef7-dfcf-43bd-9b7f-088f97e0892e/jobs/476

Failure with 4.2.0,

https://app.circleci.com/pipelines/github/biopython/biopython/474/workflows/e08f89ec-aac0-4d3f-995c-ccb903dd6fca/jobs/477

make: Entering directory '/home/circleci/project/Doc/api'
Running Sphinx v4.2.0
loading translations [en]... done
making output directory... done
[autosummary] generating autosummary for: index.rst
...
reading sources... [100%] index

WARNING: A mocked object is detected: 'Bio.Alphabet'
WARNING: A mocked object is detected: 'Bio.Restriction.Restriction'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [  0%] Bio
...
generating indices... genindex py-modindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 2 warnings.
make: *** [Makefile:20: html] Error 1

Configuration:

https://github.com/biopython/biopython/tree/fb570dfa3c04ba7570c59b992b0cf2dc50cd4a84/Doc/api

Note this in the Makefile:

SPHINXOPTS    = -W --keep-going

And this in conf.py:

# To avoid import errors.
autodoc_mock_imports = ["MySQLdb", "Bio.Restriction.Restriction"]
if version > "1.77":
    autodoc_mock_imports.append("Bio.Alphabet")

Here MySQLdb is a dependency which may not be installed.

We deliberately mock Bio.Restriction.Restriction to avoid Sphinx documenting it (very large repetitive autogenerated file), and Bio.Alphabet is now a stub from some removed code with a custom ImportError.

How to Reproduce

$ git clone https://github.com/biopython/biopython.git
$ cd biopython
$ make -C Doc/api/ html

Expected behavior

Successful build with warning mode enabled (as with Sphinx 4.1.2).

Your project

https://github.com/biopython/biopython/tree/master/Doc/api

Screenshots

No response

OS

Linux

Python version

3.9.7

Sphinx version

4.2.0

Sphinx extensions

sphinx.ext.autodoc, sphinx.ext.todo, sphinx.ext.autosummary, numpydoc

Extra tools

No response

Additional context

I suspect we have to drop -W, or is there a better way than mock to tell Sphinx/autodoc to skip certain modules?

[astrojuanlu]

Perhaps a solution could be to give the warning a subtype so it can be suppressed by setting suppress_warnings, as done in #9628 to address #9623?

[tk0miya]

I reproduced the error with this Dockerfile:

FROM python:3.9-slim

RUN apt update; apt install -y build-essential curl git unzip vim
RUN git clone https://github.com/biopython/biopython.git
WORKDIR /biopython
RUN pip install .
RUN apt install -y default-mysql-client
RUN apt install -y default-mysql-server
RUN apt install -y default-libmysqlclient-dev
RUN pip install -r ci-dependencies.txt
RUN make -C Doc/api/ html

It seems your project generates stub files using sphinx-apidoc command just before building document. And it generates Doc/api/Bio.Alphabet.rst file like below because it does not know the module is mocked.

:github_url: https://github.com/biopython/biopython/blob/master/Bio/Alphabet/__init__.py

Bio.Alphabet package
====================

Module contents
---------------

.. automodule:: Bio.Alphabet
   :members:
   :undoc-members:
   :show-inheritance:

After that, Sphinx goes to build it and detects Bio.Alphabet is already mocked via autodoc_mock_imports. I think it's not a good way to suppress the warning because the generated document is not good. It will generate the page contains headers only. I guess what you want is a document does not contain any contents about Bio.Alphabet at all, right? If so, please pass --exclude option to sphinx-apidoc call. Then, stub file will not be generated.

[peterjc]

Using the exclude option with sphinx-apidoc seems to work nicely for me, thank you.

I'm happy to close this issue - unless you think there is value in keeping it open to define a warning subtype here?

[sdhiscocks]

We've hit an issue with some mock objects that class/Enum definition point to. They are documented perfectly fine, but now getting this warning. A subtype filter would be useful.

[tk0miya]

Thank you for confirming. Closing.

[tk0miya]

@sdhiscocks I think your problem is not related to this issue. Please file another issue. Thanks,