New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
autosummary generates classes on python <=3.8 but stops working on python >3.8 #10182
Comments
It seems sphinx/sphinx/ext/autosummary/generate.py Lines 511 to 512 in a32d609
|
|
The behavior returns an empty string for the instance was changed in #20073.
It works on python >3.8 like below:
import sys
class Foo:
""" Summary of class Foo
Here comes extensive documentation.
"""
class Bar:
""" Summary of class Bar
even more extensive documentation.
"""
class LazyImporter:
__name__ = __name__
def __getattr__(self, name):
"""Lazy-Import Awesome Things
Note: this doesn't actually lazy import here, because everything is in
the same file for demo purposes. In the real world, this calls
importlib.import_module to make the magic happen.
"""
if name == "Foo":
return Foo
elif name == "Bar":
return Bar
else:
raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
lazy_importer = LazyImporter()
lazy_importer.__doc__ = """ The demp_project package
The demp_project consists of the following classes:
.. autosummary::
:toctree: _autosummary
demp_project.Foo
demp_project.Bar
"""
sys.modules[__name__] = lazy_importer sphinx-build -W ./doc/source ./doc/build output
|
@paradox-lab that does the trick 🚀 . Defining the docstring on the class instance instead of the class itself does indeed fix the issue. Since this gets resolved by your suggestion, I will close this issue. |
Describe the bug
When adding lazy importing of members to a module, sphinx fails to build the docs correctly in python 3.9 and 3.10, but works as expected up until python <=3.8.
How to Reproduce
Output on python >3.8:
Alternatively, you can check the logs of the CI that I attached to the repo to build the docs on major python versions: FirefoxMetzger/sphinx-39-bug#3
Expected behavior
The docs should build cleanly, no matter which python version is being used.
Your project
https://github.com/FirefoxMetzger/sphinx-39-bug
Screenshots
No response
OS
Tested on Windows 11 and ubuntu 20.04
Python version
3.7 - 3.10
Sphinx version
4.4.0
Sphinx extensions
No response
Extra tools
No response
Additional context
I also posted this as a question on StackOverflow: https://stackoverflow.com/questions/70978404/why-does-sphinx-autosummary-not-create-a-toctree-when-used-inside-a-class
I got some help from a user called mzjn; however, he couldn't reproduce the faulty behavior locally, which makes me wonder if I might just be going about this the wrong way.
The text was updated successfully, but these errors were encountered: