DOC: ongoing fixing of doctests

[jorisvandenbossche]

Starting with #19952, we run (some) doctests on Travis to ensure the example are kept up to date.
Currently, we only test the docstrings for Series and DataFrame, and reshape-related top level functions, and we also skip a lot of the tests.

So PRs to incrementally test more of the docstrings are very welcome, and can be good bite-sized newbie issues.

The workflow would be like this:

• Take a certain function or a certain module

• Fix the examples in the docstring(s):

  • To run the doctest for a single method, you can either use the validation script, eg:

    python scripts/validate_docstrings.py pandas.DataFrame.mean
    

    to run a full module or a subset of them, you can use something like:

    pytest --doctest-modules pandas/core/frame.py -k DataFrame
    

  • It is certainly welcome to also fix other problems with the docstring (all other errors and warnings that the validation script gives), or to actually improve the example. But I think it is also fine to do PRs just fixing the doctests as they are, so we at least can test them (so if that then somebody else improves the examples, we are sure those new examples are actually tested).

  • Some more details can be found here: http://pandas-docs.github.io/pandas-docs-travis/contributing.html#updating-a-pandas-docstring. And specifically, some tips on getting doctests to pass: http://pandas-docs.github.io/pandas-docs-travis/contributing_docstring.html#tips-for-getting-your-examples-pass-the-doctests

• When the doctests pass for a certain function or module, add those (or remove the skip) to the ones that are tested on Travis.
  For that, you need to edit the ci/code_checks.sh file. For example, for the Series tests, it looks like:

  pandas/ci/code_checks.sh

  Lines 125 to 126 in cf11f71

  	pytest --doctest-modules -v pandas/core/series.py \
  	-k"-nonzero -reindex -searchsorted -to_dict"

  Here, you could remove one of the skipped ones (the -k"-agg" syntax is to skip the doctests for Series.agg and Series.aggregate). Or add such a new line for a new module.

Good docstrings to start with are the ones for Series and DataFrame (the ones located in pandas/core/series.py, pandas/core/frame.py and pandas/core/generic.py).
After that, adding new modules like the indexing ones would be a possibility.

[Roald87]

I was looking into improving the docstrings of Series.max() and have some questions about adding the examples. Currently the method _make_stat_function is used to generate the docstring. However, this method doesn’t allow for an example to be added (as far as I can tell). Is it needed to create a new method for the min, max, std, mean etc. methods, similar to _make_cum_function for the cum methods?

Also should there be separate examples/docstrings for Series.max and DataFrame.max?

[TomAugspurger]

I think you need to have _make_stat_function take an examples argument and pass that through. See how _make_cum_function and cumsum do it.

Also should there be separate examples/docstrings for Series.max and DataFrame.max?

No, we're ok with mixing those.