DOC: Documentation Standarization Proposal

[adatasetaday]

While working on the documentation sprint, I realize that there are a bunch of common issues that are very prevalent through the documentation. Some of them remain after the sprint due to some initial confusion or methods that were not changed during the sprint. Some examples are:

• period after versionadded (the validating script was asking for it and I know my first two PRs were merged with a period at the end)
• format of axis parameter's accepted values (I've seen "None, integer or string axis name, optional", "int or string, default 0" and similar instead of "{0 or 'index', 1 or 'columns', None}, default None" type as I saw was agreed on the sprint discussions)
• return type for methods in generic.py that are used by different classes (i.e. "type of caller" vs. "A new object of same type as caller." vs. "Series or DataFrame")
• description of methods in "See Also" not matching the summary description of the method (this is mainly due to the high number of changes in the sprint)
• full method name in "See Also" (i.e. make sure the full path is used but no pandas.)
• others like the ones suggested in DOC: further clarifications to docstring guide #20309 and DOC: docstring validation script improvements #20298

I am volunteering to do these changes once we deem that all the documentation sprint PRs are completed. I would be creating a different issue for each proposed change to make sure the discussion for each of them is documented and also used to improve the validation scripts in the future.

What are your thought on this?

[TomAugspurger]

Mind moving this over to #20309? I think it overlaps pretty much with it.

[datapythonista]

Closing in favor of #20298. @adatasetaday if I missed something there, please let me know. And feel free to work in them.