DOC/CLN: Clean/Fix documentation for Window module #33608
Conversation
pandas/core/window/common.py
Outdated
| @@ -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. | |||
There was a problem hiding this comment.
Hmm what is this for? Don't think we do this anywhere else
There was a problem hiding this comment.
What do you mean? This _doc_template was there before. I just improved it, IMO.
There was a problem hiding this comment.
I don’t think we need the dot prefix? Do we do this elsewhere?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
cc @datapythonista any ideas here?
There was a problem hiding this comment.
OK, but then I would prefer to be explicit and use pandas. instead of just the .
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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!
|
Thanks @dilex42! |
* Clean/Fix documentation for Window module * add pandas prefix * remove SA05 check from ci
xref DOC: See also missing links in GroupBy.apply(), GroupBy.pipe() #31661
xref DOC: Fix SA04 errors in docstrings #28792
Added '.' before dataframe/series reference to fix missing link problem. Don't know if it's the best approach.
Changed base template that is used by some functions to return better See Also section. Hope it's ok.
Also question about Window class. It doesn't has its counterpart from Series/DF modules, its doc containing examples from Rolling part and there're only 4 functions. Is it internal base class for all windows and maybe shoul be excluded from docs or is it used somewhere maybe for creating custom windows?