You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 1summary. Wrapper 2summary. ... 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 1summary. Wrapper 2summary. ... 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 a Functions table in the Axes classes and related wrappers section of the online documentation.
Method-specific wrappers like plot_wrapper will be defined directly on the Axes with def 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 of cmap_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).
The text was updated successfully, but these errors were encountered:
lukelbd
changed the title
Clean up wrappers and consider appending to wrapper docs to matplotlib docs
Clean up wrappers and append wrapper docs to matplotlib docs
Sep 15, 2019
This is now implemented in v0.8. I use a PlotAxes class, simple %(snippet)s style docstring interpolation, and a simply concatenation of matplotlib/proplot docstrings (option 1) when rc['docstring.hardcopy'] is disabled. Option 2 would have been way too complicated and was not necessary.
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:
help(ax.plot)
, they get usage info for the wrappers and the matplotlib method. Would look something like this: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:This will have the following implications:
Axes
class methods. There will no longer be aFunctions
table in theAxes classes and related wrappers
section of the online documentation.plot_wrapper
will be defined directly on theAxes
withdef plot
.standardize_1d
will be hidden and *no longer documented explicitly *-- they will only be documented on the individual methods to which they apply.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 theinspect.getdoc
andinspect.signature
functions (for the latter see this post).The text was updated successfully, but these errors were encountered: