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.

Comment From: 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!

Comment From: 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

Comment From: kishoremusetty

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

Comment From: jbrockmendel

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

Comment From: 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.

Comment From: 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!

Comment From: KevsterAmp

take

Comment From: KevsterAmp

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

Comment From: 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

Comment From: amyfung

take

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

Comment From: fandimeng-fm

take

Comment From: ahmedbektic

take

Comment From: JuanCarlos3

take

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

Comment From: ahmedbektic

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