DOC: update the pandas.Series.shift docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
####################### Docstring (pandas.Series.shift)  #######################
################################################################################

Shift index by desired number of periods with an optional time freq.

When freq is not passed, shift the index without realign the data.
If freq is passed (in this case, the index must be date or datetime),
the index will be increased using the periods and the freq.

Parameters
----------
periods : int
    Number of periods to move, can be positive or negative.
freq : DateOffset, timedelta, or time rule string, optional
    Increment to use from the tseries module or time rule (e.g. 'EOM').
    See Notes.
axis : int or str
    Shift direction. {0, 'index'}.

Notes
-----
If freq is specified then the index values are shifted but the data
is not realigned. That is, use freq if you would like to extend the
index when shifting and preserve the original data.

Returns
-------
shifted : Series

Examples
--------
>>> df = pd.DataFrame({'Col1': [10, 20, 30, 20, 15, 30, 45],
...                    'Col2': [13, 23, 33, 23, 18, 33, 48],
...                    'Col3': [17, 27, 37, 27, 22, 37, 52]})
>>> print(df)
   Col1  Col2  Col3
0    10    13    17
1    20    23    27
2    30    33    37
3    20    23    27
4    15    18    22
5    30    33    37
6    45    48    52

>>> df.shift(periods=3)
   Col1  Col2  Col3
0   NaN   NaN   NaN
1   NaN   NaN   NaN
2   NaN   NaN   NaN
3  10.0  13.0  17.0
4  20.0  23.0  27.0
5  30.0  33.0  37.0
6  20.0  23.0  27.0

>>> df.shift(periods=1, axis=1)
   Col1  Col2  Col3
0   NaN  10.0  13.0
1   NaN  20.0  23.0
2   NaN  30.0  33.0
3   NaN  20.0  23.0
4   NaN  15.0  18.0
5   NaN  30.0  33.0
6   NaN  45.0  48.0

>>> import datetime
>>> names = ['João', 'Maria', 'Emanuel', 'Jussara', 'José']
>>> dates = [datetime.datetime(2018, 3, 1, 11, 15),
...          datetime.datetime(2018, 3, 5, 11, 15),
...          datetime.datetime(2018, 3, 10, 11, 15),
...          datetime.datetime(2018, 3, 15, 11, 15),
...          datetime.datetime(2018, 3, 20, 11, 15)]
>>> df = pd.DataFrame(data={'names': names}, index=dates)
>>> print(df)
                       names
2018-03-01 11:15:00     João
2018-03-05 11:15:00    Maria
2018-03-10 11:15:00  Emanuel
2018-03-15 11:15:00  Jussara
2018-03-20 11:15:00     José

>>> df.shift(periods=2, freq='D')
                       names
2018-03-03 11:15:00     João
2018-03-07 11:15:00    Maria
2018-03-12 11:15:00  Emanuel
2018-03-17 11:15:00  Jussara
2018-03-22 11:15:00     José

>>> df.shift(periods=75, freq='min')
                       names
2018-03-01 12:30:00     João
2018-03-05 12:30:00    Maria
2018-03-10 12:30:00  Emanuel
2018-03-15 12:30:00  Jussara
2018-03-20 12:30:00     José

See Also
--------
slice_shift: Equivalent to shift without copying data.
tshift: Shift the time index, using the index’s frequency if available.

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.shift" correct. :)
```

Labels:
name: Docs
name: Datetime
description: Datetime data dtype

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20472?src=pr&el=h1) Report
> Merging [#20472](https://codecov.io/gh/pandas-dev/pandas/pull/20472?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/4f717551b8e49ecd978bb4f5a985d6f6a96d86e9?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #20472      +/-   ##
==========================================
+ Coverage   92.22%   92.23%   +<.01%     
==========================================
  Files         161      161              
  Lines       51187    51197      +10     
==========================================
+ Hits        47209    47220      +11     
+ Misses       3978     3977       -1
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.61% <100%> (ø)` | :arrow_up: |
| #single | `42.27% <100%> (+0.01%)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20472?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20472/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.81% <100%> (ø)` | :arrow_up: |
| [pandas/core/arrays/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/20472/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL3RpbWVkZWx0YXMucHk=) | `93.75% <0%> (-0.56%)` | :arrow_down: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20472/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.87% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/20472/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `90.74% <0%> (+0.12%)` | :arrow_up: |
| [pandas/core/indexes/frozen.py](https://codecov.io/gh/pandas-dev/pandas/pull/20472/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9mcm96ZW4ucHk=) | `92.1% <0%> (+0.43%)` | :arrow_up: |
| [pandas/core/arrays/period.py](https://codecov.io/gh/pandas-dev/pandas/pull/20472/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL3BlcmlvZC5weQ==) | `98.08% <0%> (+0.59%)` | :arrow_up: |

------

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

@jreback, @WillAyd: updated.
@YitzhakAndrade seems like you've got other changes besides yours in this PR.

Can you do the next in your branch:
- `git fetch upstream`
- `git merge upstream/master`
- `git reset --soft upstream/master`
- `git commit -m "DOC: update the pandas.Series.shift docstring"`

Thanks!
Thanks for the update @YitzhakAndrade. Seems like you still have unrelated changes in this PR. Could you try what I said in my last comment?

For the next time, I think the problem can be related to using master for the changes, it's better to use a branch.
can you merge master and update
Hello @YitzhakAndrade! Thanks for updating the PR.

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


Couple of comments, agreement with points from Will and Tom.  Generally looks nice.
Thanks for the review @jbrockmendel, very useful. The docstring can surely be improved, with the raises section, and more examples, but I prefer to leave that for someone else in a separate PR, and just merge this as it is, as the PR is abandoned.
thanks @YitzhakAndrade