[DOC] Docstrings should contain minimal working examples

[ericmjl]

Brief Description of Fix

Having gone back-and-forth on this, I now think my original opinion in #329 should be made more nuanced.

Docstrings should contain minimal examples on how the function is used. They should also be tested using doctest, which I am happy to set up.

This improves the readability of the docs, and helps newcomer developers bring high-quality contributions by enforcing clarity on what is being accomplished. Notebooks still should be used, but as a series of more “elaborate” examples on data cleaning, with explanations.

@anzelpwj’s PR had a great starting point, and though it still doesn’t show both the functional and method-chaining use cases, I think it’s a great seed to build on top of.

This would involve a big effort, admittedly. I would not kickstart this until I have completed a single high-quality example (I might use flag_null as the starting point).

[anzelpwj]

So, not being a Sphinx/rST expert, how should I render the printed output of Pandas tables in my docstring?

[ericmjl]

As long as the docstrings are truly minimal examples, then they should be reasonably copy/paste-able into a Python interpreter session. We can use that output in the docstring, I think.

[anzelpwj]

I can start hacking on this, but I will need your help with the doctests, @ericmjl

[ericmjl]

@anzelpwj no problem! Can you do a thing - can you get a PR with some starter commits going, and then allow maintainers to commit to your PR directly? In that way, we can sync up on the PR.