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

Vonnievonny

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 – Bosomed

Thank you. I actually was using Napoleon and switched to numpydoc because I think it produces nicer displays. Do you prefer napoleon? – Vonnievonny

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? – Bosomed

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. – Vonnievonny

Answer 1

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

Vonnievonny

Answer 2

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.

Categorize

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

Answer 3

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.

Cloverleaf