Closed
Description
This is a follow-up to #37 and #42.
I think my current approach of documenting wrappers separately from the functions to which they apply is very cumbersome and confusing for new users (many of whom don't really know what a "wrapper" is). The old approach stems only from a lack of imagination.
A better approach would be to:
- Concatenate call signatures, parameter tables, and header descriptions from the wrappers and the original matplotlib documentation. When users call
help(ax.plot)
, they get usage info for the wrappers and the matplotlib method. Would look something like this:
Help on function plot in module proplot.axes
plot(self, ...) # concatenated call signature from wrappers and matplotlib
-----------------------
ProPlot documentation
-----------------------
Summary. Wrapper 1 summary. Wrapper 2 summary. ... Wrapper N summary.
Parameters # concatenated parameter table
----------
...params from wrapper1
...params from wrapper2
...
...params from wrapperN
--------------------------
Matplotlib documentation
--------------------------
Original docstring placed here in its entirety.
- Add an option to my
sphinx-automodapi
fork that removes the matplotlib parameters when concatenating parameter tables. Matplotlib has some funky local sphinx extensions that will get messed up -- and anyway we don't want to copy their documenation onto our website. Would look something like this:
plot(self, ...) # concatenated call signature
Summary. Wrapper 1 summary. Wrapper 2 summary. ... Wrapper N summary.
Parameters
-----------
...params from wrapper1
...params from wrapper2
...
...params from wrapperN
Other parameters
----------------
*args, **kwargs
Passed to <matplotlib native function>.
This will have the following implications:
- All wrapper-related features will be documented as
Axes
class methods. There will no longer be aFunctions
table in theAxes classes and related wrappers
section of the online documentation. - Method-specific wrappers like
plot_wrapper
will be defined directly on theAxes
withdef plot
. - "Bulk" wrappers like
standardize_1d
will be hidden and *no longer documented explicitly *-- they will only be documented on the individual methods to which they apply. - "Bulk" wrappers can be easily split up into separate functions, helping eliminate method-specific behavior inside the wrappers, e.g. the
if name == 'contour'
statements inside ofcmap_features
.
This will be tricky but I think it is really necessary to reduce new user confusion. It also has the added benefit of making it easier to merge features with matplotlib if matplotlib developers feel so inclined.
It should involve borrowing from matplotlib's docstring.py
file and using the inspect.getdoc
and inspect.signature
functions (for the latter see this post).