New warning in version 7.4 from autosummary causing automated builds to fail

[munircontractor]

Describe the bug

As of release 7.4.4, a new warning was added in autosummary in the line https://github.com/sphinx-doc/sphinx/blob/1e1356506ddd510df1e8d1a3c35f68a07752d784/sphinx/ext/autosummary/__init__.py#L644.

I run Sphinx builds in CI and on readthedocs.org with -W --keep-going flags to ensure that documents are properly built. The pipelines have started failing for the new release with no changes to the documentation itself.

The builds use autosummary for the entire package recursively:

.. autosummary::
   :toctree: python/<package_name>
   :recursive:

   <package_name>

The warnings are emitted because the generated documentation uses autosummary directive inside an automodule directive. This is a snippet from the generated documentation.

.. automodule:: <package_name>

   .. autosummary::
      :toctree:
      :recursive:

      <package_name>.<module0>
      <package_name>.<module1>

How to Reproduce

conf.py

from pathlib import Path
import sys

__this_dir = Path(__file__).absolute().parent
sys.path.append(__this_dir)

project = "foo"

extensions = [
    "sphinx.ext.autosummary",
]

# Python configuration
autodoc_default_options = {"members": True}

index.rst

.. autosummary::
   :toctree: docs/pkg
   :recursive:

   pkg

Create the pkg with

mkdir -p pkg/mod0 pkg/mod1
touch pkg/__init__.py pkg/mod0/__init__.py pkg/mod1/__init__.py

Run sphinx with

PYTHONPATH=. sphinx-build . _build/

It emits warnings and fails build with -W.

WARNING: Summarised items should not include the current module. Replace 'pkg.mod0' with 'mod0'.
WARNING: Summarised items should not include the current module. Replace 'pkg.mod1' with 'mod1'.

There doesn't seem to be a way to ignore only certain warnings in Sphinx, so I would like to keep the -W flag in my builds. Is there a way to avoid the warning or does something within autosummary need to be updated to not include the package name when documenting it?

Environment Information

Please paste all output below into the bug report template

Platform:              linux; (Linux-6.9.9-arch1-1-x86_64-with-glibc2.39)
Python version:        3.12.4 (main, Jun  7 2024, 06:33:07) [GCC 14.1.1 20240522])
Python implementation: CPython
Sphinx version:        7.4.4
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

`["sphinx.ext.autosummary"]`

Additional context

No response

[AA-Turner]

Hi @munircontractor, have you tried

suppress_warnings = [
    'autosummary.import_cycle',
]

in your conf.py?

See https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-warning-control

A

[munircontractor]

Oh, thanks for that. I could not find it when searching for a fix for this.

[valeriupredoi]

hi @AA-Turner and cheers for that sight! I believe adding the ignore in conf.py is a bit of a workaround, what is the actual fix, and will it be done in Sphinx or is it the user's responsibility? Cheers :beer:

[ilan-gold]

+1

[AA-Turner]

Please see #12609, which addresses the underlying issue. I'd be grateful for any testing.

A

[AA-Turner]

I have released Sphinx 7.4.6 with a fix.

A

[larsoner]

I am using 7.4.6 and am still hitting this issue, see this build which just used 7.4.6:

https://app.circleci.com/pipelines/github/mne-tools/mne-bids/6225/workflows/dc1e1c11-de2a-4ac0-b4d8-b3e8ee98b740/jobs/8445?invite=true#step-107-8950_109

WARNING: Summarised items should not include the current module. Replace 'mne_bids.BIDSPath' with 'BIDSPath'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.BIDSPath' with 'BIDSPath'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.BIDSPath' with 'BIDSPath'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.BIDSPath' with 'BIDSPath'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.write_raw_bids' with 'write_raw_bids'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.write_raw_bids' with 'write_raw_bids'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.BIDSPath.fpath.exists()' with 'BIDSPath.fpath.exists()'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.BIDSPath' with 'BIDSPath'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.get_anat_landmarks' with 'get_anat_landmarks'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.BIDSPath' with 'BIDSPath'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.BIDSPath' with 'BIDSPath'.
WARNING: Summarised items should not include the current module. Replace 'mne_bids.copyfiles' with 'copyfiles'.

Maybe it wasn't caught by this fix because of the autolink default role in https://github.com/mne-tools/mne-bids/blob/3c020d9c6b734d8f8f13a293bd11b175192a7ae1/doc/conf.py#L77 ? Not sure. It only happens on refs like

blah `mne_bids.BIDSPATH` blah

Refs with explicit prefixes like :class: are fine.

[AA-Turner]

Hi @larsoner, are you able to provide a reproducer please? I'll reopen the issue.

A

[larsoner]

Not minimal by any means but something like this:

git clone git@github.com:/mne-tools/mne-bids.git
cd mne-bids
git checkout 3c020d9c6b734d8f8f13a293bd11b175192a7ae1  # a commit before a workaround
pip install -ve .[doc]
cd doc
make clean && time make html SPHINXOPTS="-nWT --keep-going -Dsphinx_gallery_conf.filename_pattern=aaa"

should show the

WARNING: Summarised items should not include the current module. Replace 'mne_bids.BIDSPath' with 'BIDSPath'.

in about 20s.

[electric-coder]

@larsoner

Maybe it wasn't caught by this fix because of the autolink default role (...) Not sure. It only happens on refs like

I have to agree with the comment in the line of code you linked, namely:

default_role = "autolink"  # XXX silently allows bad syntax, someone should fix

That's why I never use default_role, when something goes wrong I don't have to second guess those default roles.

[larsoner]

Updated my comment since mne-bids has since in main it now has some workarounds (e.g., explicit roles) and pins, so checking out 3c020d9c6b734d8f8f13a293bd11b175192a7ae1 shows more relevant errors.

[AA-Turner]

If I replace default_role = "autolink" with default_role = "py:obj", the "Summarised items should not include the current module" warnings go away (and a new set of resolution errors appear), which indicates that the problem is indeed with autolink.

A

[AA-Turner]

Sphinx 7.4.7 has been released with a fix.

A

[abey79]

Thanks for looking into this issue. I'm however still seeing it with sphinx 7.4.7:

git clone https://github.com/abey79/vpype
cd vpype
git checkout 383b03b6be2161bc27f818711df1f2473e80245a
just install       # poetry install -E all --with docs,dev
just docs-clean    # rm -rf docs/_build docs/api
just docs-build    # sphinx-build -b html docs docs/_build

(requires poetry, pipx install poetry is fine)

The commit comes from this dependabot PR: https://github.com/abey79/vpype/pull/754 Previously using 7.3.7 with no issue.

[lagru]

We are also still seeing this for 7.4.7 on scikit-image's side, https://github.com/scikit-image/scikit-image/issues/7485.

[rossbar]

NetworkX is still seeing this as well with sphinx 7.4.7. FWIW networkx's docs are configured with obj as the default role.

[AA-Turner]

A minimal reproducer would be really helpful -- there are a lot of moving parts in autosummary, so reducing the problem domain does help a lot.

A

[rossbar]

NetworkX is still seeing this as well with sphinx 7.4.7. FWIW networkx's docs are configured with obj as the default role.

In NetworkX's case it turns out this was the warning working as intended. There were indeed autosummary directives that specified the redundant parent module in file where the .. currentmodule had already been set (xref networkx/networkx#7599). I only noticed this after a bit of grepping the doc source, as my first pass through the sphinx build log didn't give any indication where the warnings originated. Apologies for the noise!