Skip to content

Clean up wrappers and append wrapper docs to matplotlib docs #43

Closed
@lukelbd

Description

@lukelbd

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:

  1. 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.
  1. 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 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).

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions