Move away from doctest-style examples

[mwaskom]

Writing the API documentation examples in doctest style is constraining, with little benefit:

• It's necessary to catch outputs or otherwise prevent the return value from ending up in the REPL
• pytest can't close figures between each snippet, which can cause surprising errors or requires explicit calls to plt.close
• 4 (or more) characters are lost to the Python prompt
• Iterating on an example can be annoying because one needs to manually touch the autodoc file and then re-run the full html build.

At the same time, the doctest mechanism is useful only for making sure that the code doesn't raise; we never test specific return values (this would not be useful).

Therefore, the plan is to move towards writing the docstring examples in .ipynb format.

#2123 puts in the basic infrastructure for this and updates the new distribution plots. Other functions can be updated in future PRs, ideally a module at a time.

These rough steps should be used to update:

• Run doc/tools/extract_examples.py with the name of the function as the argument. This should generate a .ipynb file in doc/docstrings with markdown captions / code blocks.
• Read and make sure that the automatic extraction did not cause any errors
• Remove any unneeded calls to plt.close
• Remove any remaining superfluous assignments (e.g. g = g.<func>)
• Put code back on one line if it looks reasonable
• Note that suppressing the REPL output is no longer cosmetically necessary as it's stripped in the new doc buildchain. This goes for the tutorial notebooks too.
• Remove the examples from the function docstring and add ..include:: ../docstrings/<func>.rst
• Build the docs (make notebooks html) and check the output

Outstanding modules:

• relational.py (Convert relational model API examples to use notebooks #2201)
• distributions.py (Store code examples in API docs using notebooks #2123)
• categorical.py (Assorted updates to category plot documentation #2858)
• regression.py (CI: Improve example dataset usage #3020)
• matrix.py (CI: Improve example dataset usage #3020)
• axisgrid.py (Add hue as parameter in JointGrid and "hist" as a kind in jointplot #2210, Delegate hue in PairGrid to plotting functions #2234, Pre-release docs enhancements #2239)
• rcmod.py (Improve docstrings for theme-related functions #2573)
• palettes.py (Convert color palette docstrings to notebooks #3034)