DOC: Explain how our shared_docs system works

[TomAugspurger]

Enhance https://github.com/pandas-dev/pandas/blob/master/doc/source/contributing.rst with a discussion of how our _shared_docs system works.

• Why we do it (reduce duplicate docstrings, while still having some class-specific stuff)
• How it's done (Appender, _shared_docs dict, _shared_doc_kwargs)
• How to substitute values

[TheGhostHuCodes]

I was working with one of our fellow PyCon2017 sprinters figure out this system. I'll take a shot at writing this up in the docs.

[TomAugspurger]

Thanks. Post here or on gitter if you have any questions.

[AdamShamlian]

@TomAugspurger is there a "central" location where I can start to self-educate myself here? After a cursory glance through source, I couldn't seem to find a file that would be considered a "best starting place." Should I just start inferring patterns and usage by looking across source as a whole?

[TomAugspurger]

@AdamShamlian the best places to start are probably:

1. The definitions in pandas/core/generic.py:

   pandas/pandas/core/generic.py

   Line 61 in 36c309e

   # goal is to be able to define the docs close to function, while still being

   where most of these are defined
2. The uses in pandas/core/frame.py, pandas/core/series.py, etc (search for _shared_docs)
3. The implementation in pandas/util/_decorators.py:

   pandas/pandas/util/_decorators.py

   Line 126 in 36c309e

   class Substitution(object):

   (maybe it'll help you understand whats going on).

Let me know if you have questioons!

[AdamShamlian]

Ok, thanks for the tips!