Skip to content

DOC/CLN: Clean/Fix documentation for Window module #33608

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 7, 2020
Merged

DOC/CLN: Clean/Fix documentation for Window module #33608

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
640b093
Clean/Fix documentation for Window module
Apr 17, 2020
1bb4fb8
add pandas prefix
Apr 28, 2020
27e92ff
remove SA05 check from ci
Apr 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions pandas/core/window/common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,10 @@

See Also
--------
Series.%(name)s : Series %(name)s.
DataFrame.%(name)s : DataFrame %(name)s.
.Series.%(name)s : Calling object with Series data.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm what is this for? Don't think we do this anywhere else

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean? This _doc_template was there before. I just improved it, IMO.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t think we need the dot prefix? Do we do this elsewhere?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are problems with cross-links from some modules as described in #31661. I believe this is because this module is a submodule of core, like core.window or core.groupBy and it just can't see Series/DataFrame modules as it tries to look for it in core. The dot prefix fix this. But again I don't know much about sphinx so it's only speculation.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @datapythonista any ideas here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, but then I would prefer to be explicit and use pandas. instead of just the .

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But it explicitly adds pandas to text which can be not so 'clean' solution. It will look like pandas.DataFrame.rolling instead of just DataFrame.rolling

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's all right. We'll also have to fix the validation in the script. If I understand correctly we should use DataFrame.foo, and pandas.DataFrame.foo.bar. If you can take care of it too, that would be great.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I understand correctly current validation script just look if name starts with pandas and mark it as error. To make it work as desired that code needs to understand from what package the reference is made and I don't have enough experience to understand how it could be done from a quick glance.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No problem. If that check is validated, and causes the CI to fail after you make the changes, just remove its code in the validation in ci/code_checks.sh then. Thanks!

.DataFrame.%(name)s : Calling object with DataFrame data.
.Series.%(func_name)s : Similar method for Series.
.DataFrame.%(func_name)s : Similar method for DataFrame.
"""


Expand Down
10 changes: 5 additions & 5 deletions pandas/core/window/ewm.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ def func(arg):

return self._wrap_results(results, block_list, obj, exclude)

@Substitution(name="ewm")
@Substitution(name="ewm", func_name="mean")
@Appender(_doc_template)
def mean(self, *args, **kwargs):
"""
Expand All @@ -279,7 +279,7 @@ def mean(self, *args, **kwargs):
nv.validate_window_func("mean", args, kwargs)
return self._apply("ewma", **kwargs)

@Substitution(name="ewm")
@Substitution(name="ewm", func_name="std")
@Appender(_doc_template)
@Appender(_bias_template)
def std(self, bias=False, *args, **kwargs):
Expand All @@ -291,7 +291,7 @@ def std(self, bias=False, *args, **kwargs):

vol = std

@Substitution(name="ewm")
@Substitution(name="ewm", func_name="var")
@Appender(_doc_template)
@Appender(_bias_template)
def var(self, bias=False, *args, **kwargs):
Expand All @@ -313,7 +313,7 @@ def f(arg):

return self._apply(f, **kwargs)

@Substitution(name="ewm")
@Substitution(name="ewm", func_name="cov")
@Appender(_doc_template)
def cov(self, other=None, pairwise=None, bias=False, **kwargs):
"""
Expand Down Expand Up @@ -360,7 +360,7 @@ def _get_cov(X, Y):
self._selected_obj, other._selected_obj, _get_cov, pairwise=bool(pairwise)
)

@Substitution(name="ewm")
@Substitution(name="ewm", func_name="corr")
@Appender(_doc_template)
def corr(self, other=None, pairwise=None, **kwargs):
"""
Expand Down
11 changes: 5 additions & 6 deletions pandas/core/window/expanding.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,9 +88,8 @@ def _get_window(self, other=None, **kwargs):
"""
See Also
--------
DataFrame.expanding.aggregate
DataFrame.rolling.aggregate
DataFrame.aggregate
.DataFrame.aggregate : Similar DataFrame method.
.Series.aggregate : Similar Series method.
"""
)

Expand Down Expand Up @@ -172,7 +171,7 @@ def sum(self, *args, **kwargs):
nv.validate_expanding_func("sum", args, kwargs)
return super().sum(*args, **kwargs)

@Substitution(name="expanding")
@Substitution(name="expanding", func_name="max")
@Appender(_doc_template)
@Appender(_shared_docs["max"])
def max(self, *args, **kwargs):
Expand Down Expand Up @@ -208,7 +207,7 @@ def var(self, ddof=1, *args, **kwargs):
nv.validate_expanding_func("var", args, kwargs)
return super().var(ddof=ddof, **kwargs)

@Substitution(name="expanding")
@Substitution(name="expanding", func_name="skew")
@Appender(_doc_template)
@Appender(_shared_docs["skew"])
def skew(self, **kwargs):
Expand Down Expand Up @@ -252,7 +251,7 @@ def quantile(self, quantile, interpolation="linear", **kwargs):
quantile=quantile, interpolation=interpolation, **kwargs
)

@Substitution(name="expanding")
@Substitution(name="expanding", func_name="cov")
@Appender(_doc_template)
@Appender(_shared_docs["cov"])
def cov(self, other=None, pairwise=None, ddof=1, **kwargs):
Expand Down
92 changes: 47 additions & 45 deletions pandas/core/window/rolling.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -540,8 +540,8 @@ def aggregate(self, func, *args, **kwargs):

See Also
--------
Series.sum : Reducing sum for Series.
DataFrame.sum : Reducing sum for DataFrame.
.Series.sum : Reducing sum for Series.
.DataFrame.sum : Reducing sum for DataFrame.

Examples
--------
Expand Down Expand Up @@ -618,10 +618,10 @@ def aggregate(self, func, *args, **kwargs):

See Also
--------
Series.%(name)s : Calling object with Series data.
DataFrame.%(name)s : Calling object with DataFrames.
Series.mean : Equivalent method for Series.
DataFrame.mean : Equivalent method for DataFrame.
.Series.%(name)s : Calling object with Series data.
.DataFrame.%(name)s : Calling object with DataFrames.
.Series.mean : Equivalent method for Series.
.DataFrame.mean : Equivalent method for DataFrame.

Examples
--------
Expand Down Expand Up @@ -667,10 +667,10 @@ def aggregate(self, func, *args, **kwargs):

See Also
--------
Series.%(name)s : Calling object with Series data.
DataFrame.%(name)s : Calling object with DataFrames.
Series.var : Equivalent method for Series.
DataFrame.var : Equivalent method for DataFrame.
.Series.%(name)s : Calling object with Series data.
.DataFrame.%(name)s : Calling object with DataFrames.
.Series.var : Equivalent method for Series.
.DataFrame.var : Equivalent method for DataFrame.
numpy.var : Equivalent method for Numpy array.

Notes
Expand Down Expand Up @@ -727,10 +727,10 @@ def aggregate(self, func, *args, **kwargs):

See Also
--------
Series.%(name)s : Calling object with Series data.
DataFrame.%(name)s : Calling object with DataFrames.
Series.std : Equivalent method for Series.
DataFrame.std : Equivalent method for DataFrame.
.Series.%(name)s : Calling object with Series data.
.DataFrame.%(name)s : Calling object with DataFrames.
.Series.std : Equivalent method for Series.
.DataFrame.std : Equivalent method for DataFrame.
numpy.std : Equivalent method for Numpy array.

Notes
Expand Down Expand Up @@ -1030,8 +1030,8 @@ def _get_window(
"""
See Also
--------
pandas.DataFrame.rolling.aggregate
pandas.DataFrame.aggregate
.DataFrame.aggregate : Similar DataFrame method.
.Series.aggregate : Similar Series method.
"""
)

Expand Down Expand Up @@ -1146,9 +1146,9 @@ class _Rolling_and_Expanding(_Rolling):

See Also
--------
Series.%(name)s : Calling object with Series data.
DataFrame.%(name)s : Calling object with DataFrames.
DataFrame.count : Count of the full DataFrame.
.Series.%(name)s : Calling object with Series data.
.DataFrame.%(name)s : Calling object with DataFrames.
.DataFrame.count : Count of the full DataFrame.

Examples
--------
Expand Down Expand Up @@ -1243,8 +1243,10 @@ def count(self):

See Also
--------
Series.%(name)s : Series %(name)s.
DataFrame.%(name)s : DataFrame %(name)s.
.Series.%(name)s : Calling object with Series data.
.DataFrame.%(name)s : Calling object with DataFrame data.
.Series.apply : Similar method for Series.
.DataFrame.apply : Similar method for DataFrame.

Notes
-----
Expand Down Expand Up @@ -1363,10 +1365,10 @@ def max(self, *args, **kwargs):

See Also
--------
Series.%(name)s : Calling object with a Series.
DataFrame.%(name)s : Calling object with a DataFrame.
Series.min : Similar method for Series.
DataFrame.min : Similar method for DataFrame.
.Series.%(name)s : Calling object with a Series.
.DataFrame.%(name)s : Calling object with a DataFrame.
.Series.min : Similar method for Series.
.DataFrame.min : Similar method for DataFrame.

Examples
--------
Expand Down Expand Up @@ -1410,10 +1412,10 @@ def mean(self, *args, **kwargs):

See Also
--------
Series.%(name)s : Calling object with Series data.
DataFrame.%(name)s : Calling object with DataFrames.
Series.median : Equivalent method for Series.
DataFrame.median : Equivalent method for DataFrame.
.Series.%(name)s : Calling object with Series data.
.DataFrame.%(name)s : Calling object with DataFrames.
.Series.median : Equivalent method for Series.
.DataFrame.median : Equivalent method for DataFrame.

Examples
--------
Expand Down Expand Up @@ -1508,10 +1510,10 @@ def skew(self, **kwargs):

See Also
--------
Series.%(name)s : Calling object with Series data.
DataFrame.%(name)s : Calling object with DataFrames.
Series.kurt : Equivalent method for Series.
DataFrame.kurt : Equivalent method for DataFrame.
.Series.%(name)s : Calling object with Series data.
.DataFrame.%(name)s : Calling object with DataFrames.
.Series.kurt : Equivalent method for Series.
.DataFrame.kurt : Equivalent method for DataFrame.
scipy.stats.skew : Third moment of a probability density.
scipy.stats.kurtosis : Reference SciPy method.

Expand Down Expand Up @@ -1564,9 +1566,9 @@ def kurt(self, **kwargs):

See Also
--------
Series.quantile : Computes value at the given quantile over all data
.Series.quantile : Computes value at the given quantile over all data
in Series.
DataFrame.quantile : Computes values at the given quantile over
.DataFrame.quantile : Computes values at the given quantile over
requested axis in DataFrame.

Examples
Expand Down Expand Up @@ -1690,11 +1692,11 @@ def _get_cov(X, Y):

See Also
--------
Series.%(name)s : Calling object with Series data.
DataFrame.%(name)s : Calling object with DataFrames.
Series.corr : Equivalent method for Series.
DataFrame.corr : Equivalent method for DataFrame.
%(name)s.cov : Similar method to calculate covariance.
.Series.%(name)s : Calling object with Series data.
.DataFrame.%(name)s : Calling object with DataFrames.
.Series.corr : Equivalent method for Series.
.DataFrame.corr : Equivalent method for DataFrame.
cov : Similar method to calculate covariance.
numpy.corrcoef : NumPy Pearson's correlation calculation.

Notes
Expand Down Expand Up @@ -1895,8 +1897,8 @@ def _validate_freq(self):
"""
See Also
--------
Series.rolling
DataFrame.rolling
.Series.rolling : Calling object with Series data.
.DataFrame.rolling : Calling object with DataFrame data.
"""
)

Expand Down Expand Up @@ -1997,7 +1999,7 @@ def sum(self, *args, **kwargs):
nv.validate_rolling_func("sum", args, kwargs)
return super().sum(*args, **kwargs)

@Substitution(name="rolling")
@Substitution(name="rolling", func_name="max")
@Appender(_doc_template)
@Appender(_shared_docs["max"])
def max(self, *args, **kwargs):
Expand Down Expand Up @@ -2033,7 +2035,7 @@ def var(self, ddof=1, *args, **kwargs):
nv.validate_rolling_func("var", args, kwargs)
return super().var(ddof=ddof, **kwargs)

@Substitution(name="rolling")
@Substitution(name="rolling", func_name="skew")
@Appender(_doc_template)
@Appender(_shared_docs["skew"])
def skew(self, **kwargs):
Expand Down Expand Up @@ -2077,7 +2079,7 @@ def quantile(self, quantile, interpolation="linear", **kwargs):
quantile=quantile, interpolation=interpolation, **kwargs
)

@Substitution(name="rolling")
@Substitution(name="rolling", func_name="cov")
@Appender(_doc_template)
@Appender(_shared_docs["cov"])
def cov(self, other=None, pairwise=None, ddof=1, **kwargs):
Expand Down