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
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.
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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With