sphinx-doc / sphinx-doc/sphinx

Autosummary generates incorrect stub files for nested classes (openff-toolkit)

Open
#8,919 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary type:bug
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.