sphinx warning: autosummary: stub file not found for the methods of the class. check your autosummary_generate settings

Question

I have an open source package with lots of classes over different submodules. All classes have methods fit and transform, and inherit fit_transform from sklearn. All classes have docstrings that follow numpydoc with subheadings Parameters, Attributes, Notes, See Also, and Methods, where I list fit, transform and fit_transform. I copy an example of a class:

class DropFeatures(BaseEstimator, TransformerMixin):
    """
    Some description.

    Parameters
    ----------
    features_to_drop : str or list, default=None
        Variable(s) to be dropped from the dataframe

    Methods
    -------
    fit
    transform
    fit_transform
    """

    def __init__(self, features_to_drop: List[Union[str, int]]):

        some init parameters

    def fit(self, X: pd.DataFrame, y: pd.Series = None):
        """
        This transformer does not learn any parameter.

        Verifies that the input X is a pandas dataframe, and that the variables to
        drop exist in the training dataframe.

        Parameters
        ----------
        X : pandas dataframe of shape = [n_samples, n_features]
            The input dataframe
        y : pandas Series, default = None
            y is not needed for this transformer. You can pass y or None.

        Returns
        -------
        self
        """
        some functionality

        return self

    def transform(self, X: pd.DataFrame):
        """
        Drop the variable or list of variables from the dataframe.

        Parameters
        ----------
        X : pandas dataframe
            The input dataframe from which features will be dropped

        Returns
        -------
        X_transformed : pandas dataframe,
            shape = [n_samples, n_features - len(features_to_drop)]
            The transformed dataframe with the remaining subset of variables.

        """

        some more functionality

        return X

In the conf.py for Sphinx I include:

extensions = [
    "sphinx.ext.autodoc",  # Core Sphinx library for auto html doc generation from docstrings
    "sphinx.ext.autosummary",  # Create neat summary tables for modules/classes/methods etc
    "sphinx.ext.intersphinx",  # Link to other project's documentation (see mapping below)
    "sphinx_autodoc_typehints",  # Automatically document param types (less noise in class signature)
    "numpydoc",
    "sphinx.ext.linkcode",
] 


numpydoc_show_class_members = False


# generate autosummary even if no references
autosummary_generate = True
autosummary_imported_members = True

When I build the documents using sphinx-build -b html docs build, the docs are built perfectly fine, but I get 3 warnings per class, one for each of the methods, that says:

warning: autosummary: stub file not found for the methods of the class. check your autosummary_generate settings

I've exhausted all my searching resources, and I am ready to give up. Would someone know either how to prevent that warning or how to make sphinx not print it to the console?

I attach a copy of the error and I can provide a link to the PR to the repo if needed

enter image description here

Not an explanation, but as an experiment you could try the Napoleon extension instead of Numpydoc. See sphinx-doc.org/en/master/usage/extensions/napoleon.html — mzjn
– mzjn, Commented Dec 8, 2020 at 13:09
Thank you. I actually was using Napoleon and switched to numpydoc because I think it produces nicer displays. Do you prefer napoleon? — Sole Galli
– Sole Galli, Commented Dec 8, 2020 at 13:32
I don't know if I prefer one extension over the other. The suggestion to try Napoleon was "a shot in the dark". Do you get the same warnings with Napoleon? — mzjn
– mzjn, Commented Dec 8, 2020 at 14:10
I get a different warning on the fit and transform methods: "warning: duplicate object description [...] other instance in the (module/class) use :noindex: for one of them". And it also errors, because I am describing one attribute from the fit method in the init docstring, which numpydoc seems to be fine with, but napoleon not. — Sole Galli
– Sole Galli, Commented Dec 8, 2020 at 16:22

Phillyclause89 · Accepted Answer · 2025-04-29 15:18:21Z

13

Ok, after 3 days, I nailed it. The secret is add a short description to the methods in the docstrings after the heading "Methods" instead of leaving them empty as I did.

So:

class DropFeatures(BaseEstimator, TransformerMixin):
        """
        Some description.
    
        Parameters
        ----------
        features_to_drop : str or list, default=None
            Variable(s) to be dropped from the dataframe
    
        Methods
        -------
        fit:
           some description
        transform:
          some description
        fit_transform:
          some description
        """

edited Apr 29 at 15:18

Phillyclause89

6784 silver badges15 bronze badges

answered Dec 8, 2020 at 16:37

Sole Galli

1,1447 silver badges29 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

keiv.fly · Accepted Answer · 2021-02-10 15:28:18Z

7

In my case the following addition to setup.py in doc folder removed the warnings:

numpydoc_show_class_members = False

Adding Methods restricted the methods to a fixed list, which was not the behavior that I wanted.

answered Feb 10, 2021 at 15:28

keiv.fly

4,2408 gold badges30 silver badges49 bronze badges

1 Comment

IF.Francisco.ME Over a year ago

Very useful indeed, since one goal of automatic documentation is to reduce as much as static or hard coded features

Mathieu · Accepted Answer · 2022-08-09 15:30:55Z

4

If someone is still looking for this one, a better fix is to disable the creation of a toctree: numpydoc_class_members_toctree = False

As per the description:

Whether to create a Sphinx table of contents for the lists of class methods and attributes. If a table of contents is made, Sphinx expects each entry to have a separate page. True by default.

answered Aug 9, 2022 at 15:30

Mathieu

5,8467 gold badges34 silver badges66 bronze badges

Collectives™ on Stack Overflow

sphinx warning: autosummary: stub file not found for the methods of the class. check your autosummary_generate settings

3 Answers 3

Comments

1 Comment

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

Comments

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Related