Sphinx v3.1.1 causing errors for autodocumenting due to import confusion #7844
Description
Describe the bug
The pyhf docs build without errors with Sphinx v3.0.4 but they are broken by Sphinx v3.1.1. Specifically, the docs are breaking due to autodocumenting fialing to import the right module, and hence failing to produce the documentation for two sections of the API. This is shown during the build by
WARNING: don't know which module to import for autodocumenting 'optimize.opt_jax.jax_optimizer' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'optimize.opt_minuit.minuit_optimizer' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'optimize.opt_pytorch.pytorch_optimizer' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'optimize.opt_scipy.scipy_optimizer' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'optimize.opt_tflow.tflow_optimizer' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'tensor.jax_backend.jax_backend' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'tensor.numpy_backend.numpy_backend' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'tensor.pytorch_backend.pytorch_backend' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'tensor.tensorflow_backend.tensorflow_backend' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
To Reproduce
Steps to reproduce the behavior:
# In a fresh Python 3.7 virtual environment after running
# python -m pip --upgrade pip setuptools wheel
$ git clone https://github.com/scikit-hep/pyhf.git
$ cd pyhf
$ python -m pip install .[docs]
$ cd docs
$ make html # errors during build
Expected behavior
The above commands build without error for Sphinx v3.0.4, so the same behavior is expected for the minor and patch release bump to Sphinx v3.1.1.
Your project
Our project is pyhf and our nightly CI build of the docs catches this.
Environment info
Our CI that runs the docs is using GitHub Actions with the following YAML
docs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [3.7]
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Set up Python 3.7
uses: actions/setup-python@v2
with:
python-version: ${{ matrix.python-version }}
which results in
- OS: Ubuntu 16.04
- Python version: 3.7.7
- Sphinx version: 3.1.0
- Sphinx extensions: [sphinx.ext.autodoc, sphinx.ext.autosummary, sphinx.ext.coverage, sphinx.ext.mathjax, sphinx.ext.ifconfig, sphinx.ext.viewcode, sphinx.ext.githubpages, sphinxcontrib.bibtex, sphinx.ext.napoleon, sphinx_click.ext, nbsphinx, sphinx_issues, sphinx_copybutton, xref]
Additional context
This is also pyhf Issue 897
I'm also not sure if this has any overlap with Sphinx Issue #7841 or not.