I have run into this issue with Sphinx autosummary when trying to let it generate documentation for a torch.nn.Module
class.
Minimal example: https://github.com/longyuxi/sphinx-autosummary-debug
Folder structure:
.
├── README.md
├── docs
│ ├── Makefile
│ ├── api.rst
│ ├── conf.py
│ ├── index.rst
│ ├── make.bat
│ └── templates
│ ├── custom-class-template.rst
│ └── custom-module-template.rst
└── package
└── module.py
The module.py
file is taken from a PyTorch example and contains a torch.nn.Module
:
import torch
import math
class Polynomial3(torch.nn.Module):
...
I get this error when I run make html
in the docs directory.
➜ docs git:(main) ✗ make html
Running Sphinx v6.1.3
WARNING: html_static_path entry '_static' does not exist
loading pickled environment... failed
failed: Can't get attribute '_stable_repr_object' on <sphinx.deprecation._ModuleWrapper object at 0x7fe704e8b220>
[autosummary] generating autosummary for: _autosummary/package.module.Polynomial3.rst, _autosummary/package.module.rst, _autosummary/package.rst, api.rst, index.rst
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 5 source files that are out of date
updating environment: [new config] 5 added, 0 changed, 0 removed
reading sources... [100%] index
/Users/longyuxi/Documents/sphinx-autosummary-debug/docs/_autosummary/package.module.Polynomial3.rst:70: WARNING: autosummary: failed to import Polynomial3.training.
Possible hints:
* AttributeError: type object 'Polynomial3' has no attribute 'Polynomial3'
* ModuleNotFoundError: No module named 'Polynomial3'
* AttributeError: type object 'Polynomial3' has no attribute 'training'
* ImportError:
* ModuleNotFoundError: No module named 'package.module.Polynomial3'; 'package.module' is not a package
* KeyError: 'Polynomial3'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/longyuxi/Documents/sphinx-autosummary-debug/docs/api.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
/Users/longyuxi/Documents/sphinx-autosummary-debug/package/module.py:docstring of package.module.Polynomial3:1: WARNING: undefined label: 'nn-init-doc'
/Users/longyuxi/Documents/sphinx-autosummary-debug/package/module.py:docstring of package.module.Polynomial3:4: WARNING: undefined label: 'locally-disable-grad-doc'
/Users/longyuxi/Documents/sphinx-autosummary-debug/package/module.py:docstring of package.module.Polynomial3:4: WARNING: undefined label: 'locally-disable-grad-doc'
writing output... [100%] index
generating indices... genindex py-modindex done
copying linked files...
copying notebooks ...
highlighting module code... [100%] package.module
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 6 warnings.
The error seems to have originated from Sphinx trying to import training
from this nn.Module
, yet I don't understand why is it trying to do that? I have tried mocking import using autodoc_mock_imports = ['torch.nn']
or autodoc_mock_imports = ['torch.nn.Module']
, but neither of them worked. Any possible ideas / help as to how this happened?