Sphinx v3.1.0 causing errors in autoclass directive and missing title toctreee reference

[matthewfeickert]

Describe the bug

The pyhf docs build without errors with Sphinx v3.0.4 but they are broken by Sphinx v3.1.0. Specifically, the docs are breaking with errors of the form

path-to-project/docs/_generated/<code module>.rst:8 WARNING: Error in "autoclass" directive:
1 argument(s) required, 0 supplied.

.. autoclass::
   :show-inheritance:







   .. rubric:: Methods



   .. automethod:: .__init__

and

<partial node>:: WARNING: toctree contains reference to document '_generated/<code module>' that doesn't have a title: no link will be generated

A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

<Paste your command-line here which cause the problem>
# 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

I have attached the full error output of

make html &> sphinx-v3.1.0-error-log.txt

Expected behavior

The above commands build without error for Sphinx v3.0.4, so the same behavior is expected for the minor release bump to Sphinx v3.1.0.

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 894

cc @lukasheinrich @kratsg

[tk0miya]

I found the name pyhf.interpolators.code0 in python has a double meaning in pyhf. One is a module, and another is a class. New sphinx is confused by the first one.

[matthewfeickert]

@tk0miya Thank you very much for taking time to look into this and address the issue. I really appreciate it! I'll follow along on the PR you opened up. 👍