DOC: Adding example to head and tail method (#16416)
State: closed

closes #18691 
- [X] closes #16416
- [X] tests added / passed
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs
name: Output-Formatting
description: __repr__ of pandas objects, to_string

Comments:
Hello @Cheukting! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on December 15, 2017 at 13:34 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/18749?src=pr&el=h1) Report
> Merging [#18749](https://codecov.io/gh/pandas-dev/pandas/pull/18749?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/fe900cb787949ea9f949ba72f9390dcd6c83df1d?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #18749      +/-   ##
==========================================
- Coverage   91.63%   91.62%   -0.02%     
==========================================
  Files         154      154              
  Lines       51422    51422              
==========================================
- Hits        47121    47114       -7     
- Misses       4301     4308       +7
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.48% <ø> (ø)` | :arrow_up: |
| #single | `40.82% <ø> (-0.12%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/18749?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/18749/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.9% <ø> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/18749/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/18749/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.68% <0%> (-0.11%)` | :arrow_down: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/18749/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `82.91% <0%> (+0.19%)` | :arrow_up: |

------

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

can you also add a See Also section to both .head & .tail, this could close #18691 
looks like this duplicates #18746 and was a little before yours. Happy to have you contribute on any other issues though!
@jreback, I think this PR is better than #18746. Sorry for the duplicate, they were both implemented in the same sprint, and people was supposed to notify on a gitter channel which methods they were working on, but we failed to do that successfully.

This PR documents both head and tail, and I think the example is a bit clearer. I'd probably use a sorted dataframe for better clarity, and I agree with the "See also" section. Are you ok reopening this PR, and closing the other as duplicate?

@Cheukting, can you add the See also section Jeff mentioned, and sort the dataframe so it's faster for people to see that the first or last rows are the ones returned?

For the See also, in the head you should mention the tail, and viceversa. You have an example of See also section here: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.isin.html
yeah happy to have either 
will reopen and whomever wants to finish we can take
@jreback @datapythonista it is all done, let me know if there more changes needed :-)
Can I also suggest of having animals starting with A and Z in the list. So it's even more obvious (and faster to see) that the returned rows are the first and the last?

For example:

- Alligator
- Buffalo
- ...
- Whale
- Zebra

I think we can save couple of seconds on understanding the example of each new pandas user that visit these pages. Which given the number of users of pandas, can be a lot of time. :)
thanks @Cheukting