DOC: Replace `@Appender`, `@Substitution`, `@doc` with inlined docstrings

[mroeschke]

Since pandas has objects with the same API, e.g. DataFrame.fillna Series.fillna, some of these methods may leverage a shared docstring system using @Appender, @Substitution, @doc and variables named like shared_docsto dynamically generate docstring based on a template. While this helps reduce some duplication, the downsides are:

1. The shared docstring system, at minimum, adds indirection and, at worse, is less clear than a hardcoded docstring for new contributions
2. Since these docstrings are dynamic, they avoid docstring standardization and rules provide by Ruff. (These docstrings are validated by flake8 run in a subprocess, but it would be nice to remove this https://github.com/pandas-dev/pandas/blob/98c9c7f838d223e66f1459fab23ac178b29c2227/scripts/validate_docstrings.py#L203)

The task then is to replace methods that use @Appender, @Substitution or @doc with a hardcoded docstring after the function signature. Since there are many methods that use these decorators, this issue should be completed in multiple PRs ,and therefore, this issue can be worked on by multiple contributors.

For those interested in working on this issue:

1. Comment below on which directory you'll be working on, e.g. fillna
2. Submit a PR removing the above decorators from the method and inline and docstring substitutions made.
   • If a shared docstring is defined on a class inherited by others, e.g. NDFrame.fillna has the docstring for Series.fillna and DataFrame.fillna, you may need to add language that clarifies application to both e.g. Series and DataFrame
   • If a docstring is not inherited by another object, you can print the __doc__ of a method in a Python terminal and copy-paste that as the new docstring.

Once all uses of @Appender, @Substitution or @doc are removed, a separate PR to remove these objects would be welcome.

[vivupadi]

Hi.. I'd like to work on this issue. This will be my first contribution. I'm interested in working on 'dropna' method.

Update: I worked on the groupby method instead of dropna. Found that groupby uses the @Appender decorator in both frame.py and series.py files. I have submitted a PR removing those decorators and replacing them with inline docstrings for 'groupby' DataFrame and Series methods!

[scobioala]

take

UPDATES:

• Worked on ExtensionArray.repeat pandas/core/arrays/base.py
• Worked on get_window_bounds pandas/core/indexers/objects.py
• Currently, working on round, floor, ceil of TimelikeOps and strftime of DatelikeOps pandas\core\arrays\datetimelike.py

[kishoremusetty]

“I’ll work on fillna in frame.py and series.py”

[jbrockmendel]

If we're going this route, does this render #19932 unnecessary?

[mroeschke]

If we're going this route, does this render https://github.com/pandas-dev/pandas/issues/19932 unnecessary?

It appears this issue would supersede that issue.

[KevsterAmp]

@mroeschke When opening a PR for this issue, would it be better to create one PR per file, per function, or just group them together? Thanks!

[KevsterAmp]

take

[KevsterAmp]

Will work on removing @Appender and @Substitution on pandas/plotting/_core.py

[mroeschke]

When opening a PR for this issue, would it be better to create one PR per file, per function, or just group them together?

I would say per function. You can work on multiple functions if one function has few shared docstrings

[amyfung]

take

Will work on removing the @doc decorator from pandas/io

[fandimeng-fm]

take

[ahmedbektic]

take

[JuanCarlos3]

take

hello, I will be working on removing @appender from pandas/io/stata.py

edit: Will also remove @doc from pandas/io/stata.py

[ahmedbektic]

I will work on inlining the docstrings and removing @Appender decorators in pandas/core/arrays/interval.py

[G26karthik]

take - I Will be Working on DataFrame.items()

[KevsterAmp]

@mroeschke I think you've closed this issue as a mistake since I've ran ripgrep on the repo and I can still find a couple of @Appender, @Substition and @doc

[ZA1815]

take

I'd like to work on inlining the docstrings in pandas/core/window/rolling.py

[Akashisang]

take

I'd like to work on inlining the docstrings in pandas/core/window/expanding.py

[wdyy20041223]

take

I'd like to work on inlining the docstrings in pandas\core\generic.py

[Navya1707]

@mroeschke - have created a PR for DataFrame.groupby - https://github.com/pandas-dev/pandas/pull/62667 Would appreciate your review and any feedback!

[Aokizy2]

I'd like to work on inlining the docstrings in pandas\core\resample.py

[Aokizy2]

I'd also like to work on inlining the docstrings in pandas\core\window\rolling.py

[huhu-dsy]

I'd like to work on inlining the docstrings in pandas\core\readers.py

[Lonercode]

take

Aloha. I'd like to work on replacing doc decorators in pandas/core/series.py with hardcoded docstrings.

[acrossler]

take

I would like to work on replacing doc decorators in pandas/core/groupby/generic.py with hardcoded docstrings.

[Starlessnightx]

take

I would like to work on replacing doc decorators in pandas/core/indexes/multi.py with hradcoded docstrings

[mateomramos]

take

I would like to work on replacing doc decorators in pandas/core/indexes/base.py with hardcoded docstrings.

[heoh]

take

I would like to work on replacing doc decorators in pandas/core/indexes/range.py with hardcoded docstrings.

[AustinOregonState]

take

I would like to work on replacing doc decorators in pandas/core/arrays/masked.py with hardcoded docstrings.

[Geeeeeene]

take

I would like to work on replacing @Appender decorators in pandas/core/indexes/interval.py