DOC: Improve docstring for pandas.Index.repeat
State: closed

String assigned to ChiPy (Chicago Python Users Group) chapter of the Worldwide Documentation Sprint

While `Index.repeat` does accept `args` and `kwargs`, it does not pass them through to the underlying `numpy` function.

The only additional parameter the numpy function takes is `axis` ([numpy docs](https://docs.scipy.org/doc/numpy/reference/generated/numpy.repeat.html#numpy.repeat)), which is not supported by pandas:

```python
>>> pd.Index([1, 2, 3]).repeat(2, axis=2)
ValueError: the 'axis' parameter is not supported in the pandas implementation of repeat()
```

Should the *args and **kwargs be removed?

Thanks

Labels:
name: Docs

Comments:
> Should the *args and **kwargs be removed?

No, in this case we need to keep them for compatibility with numpy (long story short: if you do `np.repeat(idx)`, it will call `idx.repeat` but also pass the `axis` kwarg, which we catch with the \*\*kwargs)
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19985?src=pr&el=h1) Report
> Merging [#19985](https://codecov.io/gh/pandas-dev/pandas/pull/19985?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/607910b2a26ab7d7e94dd8ce02198631c8649513?src=pr&el=desc) will **increase** coverage by `0.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #19985      +/-   ##
==========================================
+ Coverage   91.68%   91.69%   +0.01%     
==========================================
  Files         150      150              
  Lines       49065    49112      +47     
==========================================
+ Hits        44984    45033      +49     
+ Misses       4081     4079       -2
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.07% <ø> (+0.01%)` | :arrow_up: |
| #single | `41.86% <ø> (-0.02%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/19985?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.66% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/period.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9wZXJpb2QucHk=) | `92.57% <0%> (-2.08%)` | :arrow_down: |
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `65.07% <0%> (-1.88%)` | :arrow_down: |
| [pandas/util/\_test\_decorators.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvX3Rlc3RfZGVjb3JhdG9ycy5weQ==) | `91.89% <0%> (-0.54%)` | :arrow_down: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `91.03% <0%> (-0.15%)` | :arrow_down: |
| [pandas/core/indexes/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZWxpa2UucHk=) | `96.7% <0%> (-0.13%)` | :arrow_down: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.84% <0%> (-0.05%)` | :arrow_down: |
| [pandas/core/window.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvd2luZG93LnB5) | `96.31% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.65% <0%> (-0.01%)` | :arrow_down: |
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.23% <0%> (ø)` | :arrow_up: |
| ... and [6 more](https://codecov.io/gh/pandas-dev/pandas/pull/19985/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19985?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/19985?src=pr&el=footer). Last update [607910b...8486969](https://codecov.io/gh/pandas-dev/pandas/pull/19985?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

As said in another thread, I'm more of the opinion that documenting `*args` and `**kwargs` would add value even to simply say that they are there for compatibility and shouldn't be used. But let's leave them out if the rest agree on that.

Anyway, looks really great, thank you for it!
So summary: we add `kwargs` to the Parameters section, with the message "Additional keywords have no effect but might be accepted for compatibility with numpy."

Feedback on the exact message?
I'd say "Additional keywords have no effect but are be accepted for compatibility with numpy." Note the "are" vs "might be". I think the "axis" case is an edge one.
The reason I used "might be" instead of "are", is because only some keyword (and with some values) are ignored silently, others still raise as normal (in this case is actually is only `axis=None` that is ignored, any other keyword or other value for axis will raise an error). 
But, that's also not directly clear from the "might be" :) 
Thanks for the updates, and for the nice docstring!