DOC Fix inconsistencies
State: closed

Fix a few inconsistencies in the docstrings.

Not sure how pandas community feels about these kinds of fixes (and this is my first PR to pandas). I just notice things that are different from how they occur most of the time and decided to fix them up. 

### Examples
#### Add 's' to headers
```
Example
```
to
```
Examples
```

#### Correct number of hyphens under headers
```
Yields
-------
```
to
```
Yields
------
```

#### Rewrite testcase in standard format
```
In [1]: c = pd.Categorical(list('aabca'))
```
to
```
>>> c = pd.Categorical(list('aabca'))
```




Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26301?src=pr&el=h1) Report
> Merging [#26301](https://codecov.io/gh/pandas-dev/pandas/pull/26301?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/94c8c94dccfa7934699c314420f0898d81425519?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #26301      +/-   ##
==========================================
- Coverage   91.98%   91.98%   -0.01%     
==========================================
  Files         175      175              
  Lines       52374    52374              
==========================================
- Hits        48178    48174       -4     
- Misses       4196     4200       +4
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.53% <ø> (ø)` | :arrow_up: |
| #single | `40.72% <ø> (-0.15%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/26301?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/arrays/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2Jhc2UucHk=) | `99.43% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.62% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `98.61% <ø> (ø)` | :arrow_up: |
| [pandas/core/arrays/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2RhdGV0aW1lcy5weQ==) | `97.79% <ø> (ø)` | :arrow_up: |
| [pandas/core/ops.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvb3BzLnB5) | `91.82% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/period.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9wZXJpb2QucHk=) | `92.1% <ø> (ø)` | :arrow_up: |
| [pandas/core/arrays/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2NhdGVnb3JpY2FsLnB5) | `95.96% <ø> (ø)` | :arrow_up: |
| [pandas/io/excel/\_util.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2V4Y2VsL191dGlsLnB5) | `87.32% <ø> (ø)` | :arrow_up: |
| [pandas/core/strings.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3RyaW5ncy5weQ==) | `98.86% <ø> (ø)` | :arrow_up: |
| [pandas/core/internals/blocks.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW50ZXJuYWxzL2Jsb2Nrcy5weQ==) | `94.07% <ø> (ø)` | :arrow_up: |
| ... and [14 more](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree-more) | |

------

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

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26301?src=pr&el=h1) Report
> Merging [#26301](https://codecov.io/gh/pandas-dev/pandas/pull/26301?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/7bd7fab10796a8559040880098c927cf9bb0ae4c?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #26301      +/-   ##
==========================================
- Coverage   92.04%   92.03%   -0.01%     
==========================================
  Files         175      175              
  Lines       52301    52301              
==========================================
- Hits        48141    48137       -4     
- Misses       4160     4164       +4
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.59% <ø> (ø)` | :arrow_up: |
| #single | `40.73% <ø> (-0.15%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/26301?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/arrays/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2Jhc2UucHk=) | `99.43% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.62% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `98.61% <ø> (ø)` | :arrow_up: |
| [pandas/core/arrays/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2RhdGV0aW1lcy5weQ==) | `97.79% <ø> (ø)` | :arrow_up: |
| [pandas/core/ops.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvb3BzLnB5) | `94.69% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/period.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9wZXJpb2QucHk=) | `92.1% <ø> (ø)` | :arrow_up: |
| [pandas/core/groupby/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9ncm91cGJ5LnB5) | `97.24% <ø> (ø)` | :arrow_up: |
| [pandas/core/arrays/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2NhdGVnb3JpY2FsLnB5) | `95.96% <ø> (ø)` | :arrow_up: |
| [pandas/io/excel/\_util.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2V4Y2VsL191dGlsLnB5) | `87.32% <ø> (ø)` | :arrow_up: |
| [pandas/core/strings.py](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3RyaW5ncy5weQ==) | `98.86% <ø> (ø)` | :arrow_up: |
| ... and [19 more](https://codecov.io/gh/pandas-dev/pandas/pull/26301/diff?src=pr&el=tree-more) | |

------

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

@WillAyd @datapythonista doesn't the doc-string validator catch the invalid underlines?
I don't see anything currently for underlines. Worth taking a look at; not sure how numpydoc would even parse that

I am surprised some of these weren't raising GL06 for "unknown section". This is definitely part of the CI and should be raised when the section is called say "Example" instead of "Examples"
@jreback @WillAyd 

I'm not sure why these weren't caught before but it looks like these fixes allowed the Docstring validation test to see that the docstring sections were in the wrong order. Maybe the ones that were out of order _and_ had incorrect number of underlines were not be considered sections before, so they were not considered out of order.

 I'm also not sure where I would look at the Docstring validation to confirm this is what is happening... but should I go ahead and reorder them as part of this pr as well?






Yea might as well reorder to get rid of any and all failures. FWIW the validator is located in `scripts/validate_docstrings.py` if you wanted to see how it works
Just saw that the CI is red, the problem is that the fixed sections are now detected, and they are in the wrong position with respect to the other sections. See:
```
pandas/core/indexes/multi.py(122,): error GL07: pandas.MultiIndex: Sections are in the wrong order. Correct order is: Parameters, Attributes, Methods, See Also, Notes, Examples
pandas/core/indexes/multi.py(2347,): error GL07: pandas.MultiIndex.get_loc: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas/core/indexes/multi.py(2447,): error GL07: pandas.MultiIndex.get_loc_level: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas/core/indexes/datetimes.py(95,): error GL07: pandas.DatetimeIndex: Sections are in the wrong order. Correct order is: Parameters, Attributes, Methods, See Also, Notes
pandas/core/indexes/period.py(73,): error GL07: pandas.PeriodIndex: Sections are in the wrong order. Correct order is: Parameters, Attributes, Methods, See Also, Notes, Examples
Bash exited with code '5'.
```

So, looks like numpydoc is "ignoring" (not considering header sections) the ones with the wrong hyphens, which I think makes sense. I don't think we can detect wrong section names with wrong hyphens automatically, but we could add a validation that looks for the correct section names in the docstring, and checks if the section exists (if the section has been detected by numpydoc). I think if we check that the name of the section exists in the docstring in a single line, we shouldn't have false positives.

For example, we can have in the notes `Parameters will be added in the future...` and we don't want to fail because we found the word `Parameters` without the section `Parameters`. But if in a line just `Parameters` is found, we probably should fail.

@Scowley4 if you want to work on it, can you open an issue please? Otherwise I'll create it myself so someone else can work on it.
@WillAyd Thanks for pointing me to the testing code.

@datapythonista Totally agree with the "ignoring section header" thing and have opened an issue about it that I would like to work on. #26307 
Changes look good, but CI is red. Not sure what's the problem, may be you just need to merge master, the error seems unrelated to the docstring changes.
@datapythonista Was trying to figure out what the error was. Wondering if I accidentally started down a rabbit hole (One fix exposes more problems and more and more...).

Can you be a little more explicit about what you suggest I do? Did you mean for me to merge into my master branch?
(Sorry, still pretty new to working in opensource stuff)
in you branch just do `git fetch upstream && git merge upstream/master`

this will let in your branch your changes, but applied to the last version of pandas, not the version when you created the branch
Same error. Maybe now that the sections are actually sections and in the correct order, there is something wrong inside one and that is throwing the error. I haven't found the fix yet, though...
As far as I can tell, the only place `to_panel` appears is here:

https://github.com/pandas-dev/pandas/blob/2bbc0c2c198374546408cb15fff447c1e306f99f/pandas/core/generic.py#L206-L211
I guess the above is just in `pandas/pandas`.

In the full repository:

https://github.com/pandas-dev/pandas/blob/2bbc0c2c198374546408cb15fff447c1e306f99f/doc/redirects.csv#L501

https://github.com/pandas-dev/pandas/blob/master/doc/source/reference/frame.rst

And two places in `doc/source/whatsnew` (v0.7.0 and v0.19.0)

----
It looks like this method was removed recently: #25047


@Scowley4 try merging master issue should have been fixed in #26308
@Scowley4 just had another PR go in which conflicts here - could you fix that up? Otherwise lgtm
thanks @Scowley4, nice clean up