sphinx-doc / sphinx-doc/sphinx
Autosummary generates incorrect stub files for nested classes (openff-toolkit)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
With autosummary_generate = True in conf.py and a class implemented within another class, stubs for the inner class are written as though the outer class is a module, leading to autodoc warnings.
To Reproduce
Steps to reproduce the behavior:
$ git clone https://github.com/openforcefield/openff-toolkit
$ cd openff-toolkit
$ git checkout fewer-docs-warnings
$ conda env create -f=docs/environment.yml -n openfftkdev
$ conda activate openfftkdev
$ pip install -e .
$ cd docs
$ make html
Alternatively, create a class within a class:
class Outer:
"""Wonderful docstring for an outer class"""
class Bar:
"""Another docstring"""
pass
and attempt to document it with autodoc and autosummary with autosummary_generate = True in conf.py
Expected behavior
The project should compile without autodoc: failed to import class warnings.
Your project
https://github.com/openforcefield/openff-toolkit
Environment info
- OS: Manjaro Linux
- Python version: 3.7.9
- Sphinx version: 3.4.3
- Sphinx extensions: sphinx.ext.autodoc, numpydoc, sphinx.ext.autosummary, sphinx.ext.doctest, sphinx.ext.todo, sphinx.ext.mathjax, sphinx.ext.viewcode, sphinx.ext.intersphinx, nbsphinx, m2r2
- Extra tools: Conda 4.9.2 for package and environment management
Additional context
The documentation compiles with warnings:
WARNING: autodoc: failed to import class 'AngleType' from module 'AngleHandler'; the following exception was raised:
No module named 'AngleHandler'
WARNING: autodoc: failed to import class 'BondType' from module 'BondHandler'; the following exception was raised:
No module named 'BondHandler'
WARNING: autodoc: failed to import class 'GBSAType' from module 'GBSAHandler'; the following exception was raised:
No module named 'GBSAHandler'
WARNING: autodoc: failed to import class 'ImproperTorsionType' from module 'ImproperTorsionHandler'; the following exception was raised:
No module named 'ImproperTorsionHandler'
WARNING: autodoc: failed to import class 'LibraryChargeType' from module 'LibraryChargeHandler'; the following exception was raised:
No module named 'LibraryChargeHandler'
WARNING: autodoc: failed to import class 'ProperTorsionType' from module 'ProperTorsionHandler'; the following exception was raised:
No module named 'ProperTorsionHandler'
WARNING: autodoc: failed to import class 'vdWType' from module 'vdWHandler'; the following exception was raised:
No module named 'vdWHandler'
These warnings are produced by the auto-generated stub files:
- docs/api/generated/openff.toolkit.typing.engines.smirnoff.parameters.AngleHandler.AngleType.rst
- docs/api/generated/openff.toolkit.typing.engines.smirnoff.parameters.BondHandler.BondType.rst
- docs/api/generated/openff.toolkit.typing.engines.smirnoff.parameters.GBSAHandler.GBSAType.rst
- docs/api/generated/openff.toolkit.typing.engines.smirnoff.parameters.ImproperTorsionHandler.ImproperTorsionType.rst
- docs/api/generated/openff.toolkit.typing.engines.smirnoff.parameters.LibraryChargeHandler.LibraryChargeType.rst
- docs/api/generated/openff.toolkit.typing.engines.smirnoff.parameters.ProperTorsionHandler.ProperTorsionType.rst
- docs/api/generated/openff.toolkit.typing.engines.smirnoff.parameters.vdWHandler.vdWType.rst
The following patch (with autosummary_generate_overwrite = False added to docs/conf.py) resolves the issue for the GBSAHandler instance:
--- a/docs/api/generated/openff.toolkit.typing.engines.smirnoff.parameters.GBSAHandler.GBSAType.rst
+++ b/docs/api/generated/openff.toolkit.typing.engines.smirnoff.parameters.GBSAHandler.GBSAType.rst
@@ -3,10 +3,10 @@
.. currentmodule:: openff.toolkit.typing.engines.smirnoff.parameters
-.. autoclass:: GBSAHandler.GBSAType
+.. autoclass:: openff.toolkit.typing.engines.smirnoff.parameters::GBSAHandler.GBSAType
- .. automethod:: __init__
+ .. automethod:: openff.toolkit.typing.engines.smirnoff.parameters::GBSAHandler.GBSAType.__init__
.. rubric:: Methods
This patch is based on advice from Stack Overflow. Obviously manually editing auto-generated files is not an acceptable solution.
I'd be happy to submit a PR if a maintainer could suggest their preferred way of fixing this :)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/conf.py and the generated stubs under docs/api/generated/, then reproduce the warnings with make html using the documented environment. Trace how autosummary handles nested classes such as GBSAHandler.GBSAType; done means generated stubs use importable references and the documentation builds without autodoc import warnings.
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