numpy / numpy/numpydoc

'autosummary: failed to import' when using numpydoc instead of sphinx.ext.napoleon

Open
#426 9 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
355
Forks
181
Avg merge
1d 9h
Merged PRs (30d)
3

Description

I've been playing with doc build for a while now, using this sandbox repository with a simple project and code-base. I am running into an issue a bit similar to #80, I'm at a complete loss and I only managed to narrow it down to 'bad things happen when I used numpydoc on macOS and on Windows'.

When building the documentation on my Linux PC, or on the GitHub CI with this workflow, the build works without any issue. Here is the current version deployed.
When building the documentation locally on my Windows or macOS PC, I'm greeted with 52 similar warnings. You can find 2 of them below:

C:\Users\Mathieu\Documents\git\mscheltienne\simple-stimuli\stimuli\audio\noise.py:docstring of stimuli.audio.noise.Noise:36: WARNING: autosummary: failed to import color.
Possible hints:
* ModuleNotFoundError: No module named 'color'
* AttributeError: module 'stimuli.audio' has no attribute 'color'
* ModuleNotFoundError: No module named 'stimuli.audio.color'
* KeyError: 'color'
* AttributeError: module 'stimuli.audio.Noise' has no attribute 'color'
* ModuleNotFoundError: No module named 'stimuli.audio.Noise.color'; 'stimuli.audio.Noise' is not a package
* ValueError: not enough values to unpack (expected 2, got 1)
C:\Users\Mathieu\Documents\git\mscheltienne\simple-stimuli\stimuli\audio\noise.py:docstring of stimuli.audio.noise.Noise:36: WARNING: autosummary: failed to import duration.
Possible hints:
* ModuleNotFoundError: No module named 'stimuli.audio.duration'
* AttributeError: module 'stimuli.audio' has no attribute 'duration'
* ModuleNotFoundError: No module named 'stimuli.audio.Noise.duration'; 'stimuli.audio.Noise' is not a package
* ModuleNotFoundError: No module named 'duration'
* KeyError: 'duration'
* AttributeError: module 'stimuli.audio.Noise' has no attribute 'duration'
* ValueError: not enough values to unpack (expected 2, got 1)

And obviously, the documentation is a bit broken. Based on the pasted warnings, take the Noise class defined in noise.py: Left -> local (windows). Right -> CI (ubuntu). Both build on the same commit,

image


Why is numpydoc involved?

It turns out that if I remove numpydoc from the extensions and load sphinx.ext.napoleon instead, the doc builds without warnings (except the missing x-ref since they are not defined anymore). However, the render is missing the summary tables, so at least it makes sense that warnings about those tables are missing:

image

And the attributes and method tables that are failing are a feature of numpydoc, right?

In both cases, the generated .rst is the same:

stimuli.audio.Noise
===================

.. currentmodule:: stimuli.audio

.. autoclass:: Noise
   :members:
   :inherited-members:

I tried with different templates, and with the default templates, but nothing changed.


I'm at a complete loss as to why the doc build is failing on macOS or Windows, and not on Linux, I'm not even sure it's a bug, or an issue with my configuration. Here is a couple of lines to set-up the project if you want to give it a try:

git clone https://github.com/mscheltienne/simple-stimuli
python3 -m venv test --copies
source test/bin/activate
python3 -m pip install --upgrade pip setuptools wheel
cd simple-stimuli
python3 -m pip install -e ".[doc]"
cd doc
make html

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the documentation build using the linked simple-stimuli sandbox and the documented environment setup, comparing Linux or CI with Windows and macOS. Start with stimuli/audio/noise.py and the generated autosummary for stimuli.audio.Noise, then compare builds using numpydoc versus sphinx.ext.napoleon; done means the platform-specific import warnings and broken summary tables are resolved.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.