inherit documentation of args and kwargs from sub-functions

[lukashergt]

Could docrep be potentially of interest for inheriting documentation of parameters from one function to another?

This could be the solution to avoiding copy-pasting of docs and to "good docs are better than no docs, but no docs are better than bad docs".

Example of a use-case: Currently samples.plot_1d's docstring only informs about one argument: axes. It might be helpful for the user to also see arguments going into samples.plot, though. In particular the plot_type argument which is documented in plot would be useful to know about in plot_1d.

[williamjameshandley]

This does sound pretty good. It looks like it should be compatible with our sphinx rtd implementation too, since we follow numpy conventions.

1. Are you able to submit a minor PR with an example of it in action for a subsection of the code?
2. Are there any other similar packages? How do numpy, scipy or matplotlib implement their nested documentation?

[lukashergt]

1. done

2. matplotlib does some docstring interpolation but the documentation on how to do it is rather opaque.

[williamjameshandley]

partially resolved by #239