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

[jorisvandenbossche]

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

[jreback]

can you add sub-section refs

[datapythonista]

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]

Codecov Report

Merging #20037 into master will decrease coverage by 0.01%.
The diff coverage is n/a.

@@            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%)	⬇️
#single	41.86% <ø> (-0.01%)	⬇️

Impacted Files	Coverage Δ
pandas/plotting/_converter.py	65.07% <0%> (-1.74%)	⬇️
pandas/io/packers.py	88.2% <0%> (+0.88%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update fd010de...1c94ab4. Read the comment docs.

[jorisvandenbossche]

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.

[jorisvandenbossche]

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?

[jorisvandenbossche]

This was included in the merge of #19704, so closing.