DOC: add small guide on how to write examples that pass doctests
State: closed

Some initial attention points for getting doctests passing (this would eventually fit in the docstring guide, putting it in contributing.rst for now, will move once the other is merged).

Anybody else thinks of typical gotcha's?

cc @datapythonista 

Labels:
name: Docs

Comments:
One that comes to my mind is reading from files, like `pandas.read_csv`, that I assume it fails, as the file won't be found.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20037?src=pr&el=h1) Report
> Merging [#20037](https://codecov.io/gh/pandas-dev/pandas/pull/20037?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/fd010de51bd21e4240daac2e1fd0044c65a45091?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/20037/graphs/tree.svg?token=eZ4WkYLtcO&src=pr&width=650&height=150)](https://codecov.io/gh/pandas-dev/pandas/pull/20037?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20037      +/-   ##
==========================================
- Coverage   91.71%   91.69%   -0.02%     
==========================================
  Files         150      150              
  Lines       49104    49112       +8     
==========================================
- Hits        45035    45033       -2     
- Misses       4069     4079      +10
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.07% <ø> (-0.02%)` | :arrow_down: |
| #single | `41.86% <ø> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20037?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/20037/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `65.07% <0%> (-1.74%)` | :arrow_down: |
| [pandas/io/packers.py](https://codecov.io/gh/pandas-dev/pandas/pull/20037/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3BhY2tlcnMucHk=) | `88.2% <0%> (+0.88%)` | :arrow_up: |

------

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

> One that comes to my mind is reading from files, like pandas.read_csv, that I assume it fails, as the file won't be found.

The question is what to do in general for those IO functions. 
Do we want to show actual output? But then there needs to be an actual file to read in, as otherwise it also does not say much. 

In principle you could always create a small file to then read back in.
In general, for read functions, we could do like:

```
For the example, we first create a small example csv file

>>> df = pd.DataFrame(...)
>>> df.to_csv('file.csv')

We can now read that in with read_csv:

>>> pd.read_csv('file.csv')

read with option:

>>> ...
```

for write functions that is a bit more difficult, as you don't directly see what you get. Maybe just showing the basic usage (method call) and then referring to user guide is enough for those?
This was included in the merge of https://github.com/pandas-dev/pandas/pull/19704, so closing.