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