0

I'm trying to understand better doc-builds by working on this sandbox project: https://github.com/mscheltienne/simple-stimuli The current documentation, built by this CI, is available here: https://mscheltienne.github.io/simple-stimuli/dev/index.html

The built on the CI works fine and doesn't issue any warning (and the HTML looks good). However, this is not the case of the built locally (it was, but not anymore, and I fail to see what changed). Here are 2 of the 46 similar warnings issued:

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

For some reason, it fails to document the methods of the classes defined in the package.

The build started failing when I checkout locally the branch gh-pages, which is not a python package, and since it was installed in editable mode in the environment, bad things happened :) But cloning the repository again and installing it in a fresh environment does not fix the doc build.. so that was not the issue.

EDIT:

To clone the repository, I usually use GitHub Desktop, but let's give the equivalent in command lines:

git clone https://github.com/mscheltienne/simple-stimuli

python3 -m venv test --copies
# on macOS/Linux
source test/bin/activate
# on Windows
test/Scripts/activate.bat
pip install --upgrade pip setuptools wheel

cd simple-stimuli
pip install -e .[all]
cd doc
make html

I did try to use the same command as the one I've set on the CI to build the documentation instead of the make file: sphinx-build ./main/doc ./doc-build/dev -W --keep-going (with the correct folders of course). Same outcome! (at least that make sense).

And I'm getting the same error on both my macOS laptop and my windows PC. But it does work on Linux (which is coherent with the CI running as well on ubuntu-latest).

Mathieu
  • 5,410
  • 6
  • 28
  • 55
  • Please include all the commands you used to clone, install, and build the project's docs by editing your question. – Steve Piercy Aug 17 '22 at 09:40
  • @StevePiercy Here you go, nothing fancy, and this is not the only project on which I work or that I maintain.. the issue I'm facing is a first! Other doc build on other projects are working fine. And the setup is very similar. – Mathieu Aug 17 '22 at 10:37
  • I followed your steps on macOS, with the following changes: `git clone https://github.com/mscheltienne/simple-stimuli.git; cd simple-stimuli; python3 -m venv env`. Then `$ pip install -e ".[all]"`. I see the exact same thing you do. Then I checked your CI. Do these steps need to be performed locally? https://github.com/mscheltienne/simple-stimuli/blob/main/.github/workflows/doc.yml#L23-L31 They had no effect for me. I am at a total loss as to why the imports fail for Sphinx. Sorry. You could try https://duckduckgo.com/?q=WARNING%3A+autosummary%3A+failed+to+import – Steve Piercy Aug 18 '22 at 06:44
  • @StevePiercy So you added the quotes because of the zsh shell. The steps you copy/pasted do not need to be performed locally. The package delivers sounds, and thus requires a soundcard to work. On CIs, that's a bit tricky and you need a virtual soundcard. For the GitHub runners, only the macOS runner is shipped with one by default, so the ubuntu and windows runner need those extra-steps. Thank you for trying! I am glad at least the problem is reproducible! I'm at a complete loss as well.. – Mathieu Aug 18 '22 at 06:50
  • The errors go away if you replace `numpydoc` with `napoleon`.. finally a lead!! – Mathieu Aug 18 '22 at 11:13

0 Answers0