Sphinx autosummary: dataclass inheritance

Question

Following code makes Sphinx autosummary fail:

@dataclasses.dataclass
class Foo:
    bar: int


class FooChild(Foo):
    pass

My autosummary template (_templates/autosummary/class.rst):

{{ name | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
   :members:

   {% block attributes %}
   {% if attributes %}
   .. rubric:: {{ _('Attributes') }}

   .. autosummary::
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

When running sphinx-build -j 2 -W -b html docs docs/gh-pages I get following warning:

Warning, treated as error:
~/path/docs/generated/module.FooChild.rst:14:autosummary: 
failed to import FooChild.bar.

I need to treat warnings as errors because otherwise documentation in my project will quickly degrade, but I would like to either fix root cause of this one or ignore this specific warning.

I couldn't find any way to ignore a warning from source code comments, nor to selectively suppress warnings from Sphinx configuration. Please help!

EDIT: here is what generated FooChild.rst file looks like:

FooChild
========
.. currentmodule:: package.module

.. autoclass:: FooChild
   :members:

   .. rubric:: Attributes
   .. autosummary::
      ~FooChild.bar

I have a conf.py adding api.rst to toctree, api.rst is designed to trigger autosummary to create documentation for all modules and classes, in this example just module.py.

API Overview
************

.. currentmodule:: package
.. autosummary::
   :toctree: generated
   :recursive:

   module

This is an import error and Sphinx cannot find your module. What is the path in your `conf.py`? Do you have an `__init__.py` file in your module's directory? What is in your `module.FooChild.rst`? — Steve Piercy, Apr 12 '22 at 12:06
@StevePiercy I do have `__init__.py`, and the same error occurs with or w/o having Foo and FooChild imported there. I don't have `module.FooChild.rst`, it's generated by autosummary extension. I've added generated file at the end of my question, as well as info about conf.py and autosummary entry point. — ikamen, Apr 13 '22 at 16:15
Note that without FooChild, documentation is successfully generated and contains class Foo, so I think there is no problem with paths setup. — ikamen, Apr 13 '22 at 16:16
This file is generated, it's overwritten if I modify it to ~bar. — ikamen, Apr 14 '22 at 06:54
yes, I can change `~{{ name }}.{{ item }}` to `~{{ item }}`, this leads to error changing to `module.Foo.rst:13:autosummary: failed to import bar.` — ikamen, Apr 19 '22 at 17:32

Boschie · Answer 1 · 2022-04-11T13:16:50.797

While it doesn't fix the root cause, but you asked for a way to ignore this warning:

You could add __all__ to your module, that doesn't include FooChild. This way it will be ignored by autosummary.

From documentation autosummary_ignore_module_all https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html:

If False and a module has the __all__ attribute set, autosummary documents every member listed in __all__ and no others. Default is True

Note that if an imported member is listed in __all__, it will be documented regardless of the value of autosummary_imported_members. To match the behaviour of from module import *, set autosummary_ignore_module_all to False and autosummary_imported_members to True.

New in version 4.4.

Sphinx autosummary: dataclass inheritance

1 Answers1