DOC/CLN: clean-up shared_docs in generic.py
State: closed

xref https://github.com/pandas-dev/pandas/pull/20016

Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20074?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@9caf048`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20074/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/20074?src=pr&el=tree)

```diff
@@            Coverage Diff            @@
##             master   #20074   +/-   ##
=========================================
  Coverage          ?   91.69%           
=========================================
  Files             ?      150           
  Lines             ?    49108           
  Branches          ?        0           
=========================================
  Hits              ?    45031           
  Misses            ?     4077           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.08% <100%> (?)` | |
| #single | `41.84% <95.65%> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20074?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/sparse/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20074/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3BhcnNlL3Nlcmllcy5weQ==) | `95.2% <100%> (ø)` | |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/20074/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.18% <100%> (ø)` | |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20074/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.85% <100%> (ø)` | |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20074/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.81% <100%> (ø)` | |
| [pandas/core/panel.py](https://codecov.io/gh/pandas-dev/pandas/pull/20074/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcGFuZWwucHk=) | `97.3% <100%> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20074?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20074?src=pr&el=footer). Last update [9caf048...404845b](https://codecov.io/gh/pandas-dev/pandas/pull/20074?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

cc @jorisvandenbossche 
@jorisvandenbossche needs rebase but I think the consensus is this is pretty much good to go
Hello @jorisvandenbossche! Thanks for updating the PR.

 - There are no PEP8 issues in the file [`pandas/core/frame.py`](https://github.com/jorisvandenbossche/pandas/blob/47ba08a85fa0907fc66877ad725840130db2f7ff/pandas/core/frame.py) !

 - There are no PEP8 issues in the file [`pandas/core/generic.py`](https://github.com/jorisvandenbossche/pandas/blob/47ba08a85fa0907fc66877ad725840130db2f7ff/pandas/core/generic.py) !

 - There are no PEP8 issues in the file [`pandas/core/panel.py`](https://github.com/jorisvandenbossche/pandas/blob/47ba08a85fa0907fc66877ad725840130db2f7ff/pandas/core/panel.py) !

 - There are no PEP8 issues in the file [`pandas/core/series.py`](https://github.com/jorisvandenbossche/pandas/blob/47ba08a85fa0907fc66877ad725840130db2f7ff/pandas/core/series.py) !

 - There are no PEP8 issues in the file [`pandas/core/sparse/series.py`](https://github.com/jorisvandenbossche/pandas/blob/47ba08a85fa0907fc66877ad725840130db2f7ff/pandas/core/sparse/series.py) !


@datapythonista thanks!

(don't merge yet, the failure is relevant)
So changing `@Appender(_shared_docs['reindex'] % _shared_doc_kwargs)` with `@Appender(NDFrame.reindex.__doc__ % _shared_doc_kwargs)` fails if there is the optimization to remove docstrings (`__doc__` will then be None, and the `%` operation will fail). 

Are we fine with changing it to (using our `Subsitution` decorator which handles this corner case):

```
@Substitution(**_shared_doc_kwargs)
@Appender(NDFrame.reindex.__doc__)
```

(this is already used in some places)

Or do we rather want that the `Appender` can already handle this (`@Appender(NDFrame.reindex.__doc__, _shared_doc_kwargs)` or `@Appender(NDFrame.reindex.__doc__, **_shared_doc_kwargs)`) ?

Since we already do the first, I will update the PR with this
+1 for the first. We can review whether `Appender` and `Substitution` can be improved in the future, but if the first works, I think it's better to use it for now.
> [...] fails if there is the optimization to remove docstrings

Just opened #22927 that I think addresses this (although now that I look at your comment more closely, I no longer think it makes a difference)