DOC: Spellcheck of gotchas.rst (FAQ page)
State: closed

Minor changes to the documentation, specifically `gotchas.rst`, i.e. the FAQ page.

* Function/method references as links.
* Consistent double backticks ` `` ` around Series, DataFrame.
* Minor rephrasing of a sentence or two, added some missing punctuation.
* Replaced `.. ipython::` with `ipython:: python` twice, as the former is not sufficient to make the iPython code render in the docs.

Reviews/comments very welcome.



Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19747?src=pr&el=h1) Report
> Merging [#19747](https://codecov.io/gh/pandas-dev/pandas/pull/19747?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/abc4ef9132d8bcc8ad987c18fdd757595fd65d8c?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/19747/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/19747?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #19747      +/-   ##
==========================================
- Coverage    91.6%    91.6%   -0.01%     
==========================================
  Files         150      150              
  Lines       48908    48864      -44     
==========================================
- Hits        44804    44763      -41     
+ Misses       4104     4101       -3
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.98% <ø> (-0.01%)` | :arrow_down: |
| #single | `41.75% <ø> (-0.03%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/19747?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/reshape/tile.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS90aWxlLnB5) | `90.25% <0%> (-2.69%)` | :arrow_down: |
| [pandas/util/\_decorators.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvX2RlY29yYXRvcnMucHk=) | `81.66% <0%> (-0.74%)` | :arrow_down: |
| [pandas/util/\_validators.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvX3ZhbGlkYXRvcnMucHk=) | `96.34% <0%> (-0.47%)` | :arrow_down: |
| [pandas/core/ops.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvb3BzLnB5) | `96.45% <0%> (-0.32%)` | :arrow_down: |
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.32% <0%> (-0.25%)` | :arrow_down: |
| [pandas/core/indexes/range.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9yYW5nZS5weQ==) | `95.65% <0%> (-0.1%)` | :arrow_down: |
| [pandas/core/sparse/array.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3BhcnNlL2FycmF5LnB5) | `91.38% <0%> (-0.09%)` | :arrow_down: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `90.56% <0%> (-0.07%)` | :arrow_down: |
| [pandas/core/algorithms.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYWxnb3JpdGhtcy5weQ==) | `94.14% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.22% <0%> (-0.01%)` | :arrow_down: |
| ... and [15 more](https://codecov.io/gh/pandas-dev/pandas/pull/19747/diff?src=pr&el=tree-more) | |

------

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

> Replaced .. ipython:: with ipython:: python twice, as the former is not sufficient to make the iPython code render in the docs.

would welcome this an additional check in the lint.sh
There are certain legitimate use cases of `.. ipython::` blocks with the `python` added, so I am not sure we can add such a lint check in general. 

For example, the code snippet here is done with a bar `.. ipython::` on purpose: http://pandas.pydata.org/pandas-docs/stable/basics.html#iteritems. I don't recall exactly, but I think it was a problem with the for loop in a ipython::python directive (but it might be that that works correctly by now, but we would need to check).
small question. looks fine. can you rebase and push again just to make sure.
@jreback no, this is not ready, see my comment

BTW, can you answer https://github.com/pandas-dev/pandas/issues/19750 before merging this?
Ah, I didn't see that the CI was passing. But since we still have occurrences of `.. ipython::` without `python` in our docs, that means the lint is check is actually not working?
I believe this PR is good to go now.

Thanks for double-checking the lint @jorisvandenbossche. It seems like it was not working, glad you caught it. Since there might be cases which warrant `.. ipython::` without `python`, I have removed the lint for now. In the particular case of the code blocks where I added `python` in this PR, the code is [currently not rendered](http://pandas-docs.github.io/pandas-docs-travis/gotchas.html#using-the-in-operator) - so adding `python` seems correct as it now renders on my local doc build.
``.. ipython:: without python``

I guess, but why can't we cross this bridge i its actually needed. not-specifying python makes this look not so great and easy enough to avoid with a lint check.
The cases of `.. ipython:: without python` that @tommyod fixed, where indeed correct fixes (it were cases where we forgot this, and by forgetting it indeed did not render correctly in the docs). 

But as I mentioned above, there are *other* cases where this was done on purpose (https://github.com/pandas-dev/pandas/pull/19747#issuecomment-366547716). And in those they are currently rendered fine. I am not sure if those cases are actually needed, but if someone wants to remove them, we should first check the docs build correctly without them.
ok that’s fine 
better to have automatically checks in things if possible otherwise end up with inconsistencies over time