pythonpython-sphinxnumpydocsphinx-napoleon

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


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


Solution

  • 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