DOC: update the pandas.Index.duplicated and pandas.Series.duplicated 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"
- [ ] 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:

Method `pandas.Index.duplicated`:
```
################################################################################
##################### Docstring (pandas.Index.duplicated)  #####################
################################################################################

Indicate duplicate index values.

Duplicated values are indicated as ``True`` values in the resulting
array. Either all duplicates, all except the first or all except the
last occurrence of duplicates can be indicated.

Parameters
----------
keep : {'first', 'last', False}, default 'first'
    - 'first' : Mark duplicates as ``True`` except for the first
      occurrence.
    - 'last' : Mark duplicates as ``True`` except for the last
      occurrence.
    - ``False`` : Mark all duplicates as ``True``.

Examples
--------
By default, for each set of duplicated values, the first occurrence is
set on False and all others on True:

>>> idx = pd.Index(['lama', 'cow', 'lama', 'beetle', 'lama'])
>>> idx.duplicated()
array([False, False,  True, False,  True], dtype=bool)

which is equivalent to

>>> idx.duplicated(keep='first')
array([False, False,  True, False,  True], dtype=bool)

By using 'last', the last occurrence of each set of duplicated values
is set on False and all others on True:

>>> idx.duplicated(keep='last')
array([ True, False,  True, False, False], dtype=bool)

By setting keep on ``False``, all duplicates are True:

>>> idx.duplicated(keep=False)
array([ True, False,  True, False,  True], dtype=bool)

Returns
-------
numpy.ndarray

See Also
--------
pandas.Series.duplicated : equivalent method on pandas.Series

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameter "keep" description should start with capital letter
```

Method `pandas.Series.duplicated`:
```
################################################################################
##################### Docstring (pandas.Series.duplicated) #####################
################################################################################

Indicate duplicate Series values.

Duplicated values are indicated as ``True`` values in the resulting
Series. Either all duplicates, all except the first or all except the
last occurrence of duplicates can be indicated.

Parameters
----------
keep : {'first', 'last', False}, default 'first'
    - 'first' : Mark duplicates as ``True`` except for the first
      occurrence.
    - 'last' : Mark duplicates as ``True`` except for the last
      occurrence.
    - ``False`` : Mark all duplicates as ``True``.

Examples
--------
By default, for each set of duplicated values, the first occurrence is
set on False and all others on True:

>>> animals = pd.Series(['lama', 'cow', 'lama', 'beetle', 'lama'])
>>> animals.duplicated()
0    False
1    False
2     True
3    False
4     True
dtype: bool

which is equivalent to

>>> animals.duplicated(keep='first')
0    False
1    False
2     True
3    False
4     True
dtype: bool

By using 'last', the last occurrence of each set of duplicated values
is set on False and all others on True:

>>> animals.duplicated(keep='last')
0     True
1    False
2     True
3    False
4    False
dtype: bool

By setting keep on ``False``, all duplicates are True:

>>> animals.duplicated(keep=False)
0     True
1    False
2     True
3    False
4     True
dtype: bool

Returnsinde
-------
pandas.core.series.Series

See Also
--------
pandas.Index.duplicated : equivalent method on pandas.Index

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameter "keep" description should start with capital letter
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

- We (Ghent chapter) decided that an additional line of text (with capital) was less useful than starting with explaining the list of options.

Instead of using the template-based version used before, we split out both docstrings and made a separate for the `Index` versus the `Series`. This introduces some redundancy and overlap (basically, the `keep` argument, also shared with `drop_duplicated`), but provides a cleaner option by having the examples written inside the docstring of the methods and not *somewhere* else in the code.

Labels:
name: Docs
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode

Comments:
@TomAugspurger we will have the same discussion here about sharing the docstrings or not
FWIW I have a slight preference for sharing. Don't have a strong opinion though.
Ideally I agree that sharing would be nice.
> Ideally I agree that sharing would be nice.

@jreback does "ideally" mean you are OK with this "practical" solution? :-)

As I said in https://github.com/pandas-dev/pandas/pull/20114#issuecomment-372027305 as well, in principle we could take out the parameter section as shared part and inject that. But not sure that will be that practical, as the question is then where to put that.

well ideally this *should* be much more shared, it ends up being a lot of duplicate text. (this means if we can fix it to make it shared would be the best), but if its too complicated for now, then ok too.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20117?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@e6c2647`). [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/20117/graphs/tree.svg?token=eZ4WkYLtcO&src=pr&width=650&height=150)](https://codecov.io/gh/pandas-dev/pandas/pull/20117?src=pr&el=tree)

```diff
@@            Coverage Diff            @@
##             master   #20117   +/-   ##
=========================================
  Coverage          ?    91.7%           
=========================================
  Files             ?      150           
  Lines             ?    49148           
  Branches          ?        0           
=========================================
  Hits              ?    45070           
  Misses            ?     4078           
  Partials          ?        0
```

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

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20117?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20117/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYmFzZS5weQ==) | `96.77% <ø> (ø)` | |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20117/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.66% <100%> (ø)` | |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/20117/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.06% <100%> (ø)` | |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20117/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.84% <100%> (ø)` | |
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/20117/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `97.31% <100%> (ø)` | |

------

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

Thanks @stijnvanhoey