René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Clean up wrappers and append wrapper docs to matplotlib docs","articleBody":"This is a follow-up to #37  and #42.\r\n\r\nI 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.\r\n\r\nA better approach would be to:\r\n\r\n1. 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:\r\n\r\n```less\r\nHelp on function plot in module proplot.axes\r\n\r\nplot(self, ...) # concatenated call signature from wrappers and matplotlib\r\n   -----------------------\r\n   ProPlot documentation\r\n   -----------------------\r\n   Summary. Wrapper 1 summary. Wrapper 2 summary. ... Wrapper N summary.\r\n\r\n   Parameters # concatenated parameter table\r\n   ----------\r\n   ...params from wrapper1\r\n   ...params from wrapper2\r\n   ...\r\n   ...params from wrapperN\r\n\r\n   --------------------------\r\n   Matplotlib documentation\r\n   --------------------------\r\n   Original docstring placed here in its entirety.\r\n```\r\n\r\n2. 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:\r\n\r\n```less\r\nplot(self, ...) # concatenated call signature\r\n   Summary. Wrapper 1 summary. Wrapper 2 summary. ... Wrapper N summary.\r\n\r\n   Parameters\r\n   -----------\r\n   ...params from wrapper1\r\n   ...params from wrapper2\r\n   ...\r\n   ...params from wrapperN\r\n\r\n   Other parameters\r\n   ----------------\r\n   *args, **kwargs\r\n       Passed to \u003cmatplotlib native function\u003e.\r\n\r\n```\r\n\r\nThis will have the following implications:\r\n\r\n* 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.\r\n* Method-specific wrappers like `plot_wrapper` will be defined directly on the `Axes` with `def plot`.\r\n* \"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.\r\n* \"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`.\r\n\r\nThis 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.\r\n\r\nIt should involve borrowing from matplotlib's `docstring.py` file and using the `inspect.getdoc` and `inspect.signature` functions (for the latter see [this post](https://stackoverflow.com/a/33112180/4970632)).","author":{"url":"https://github.com/lukelbd","@type":"Person","name":"lukelbd"},"datePublished":"2019-09-15T22:48:50.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/43/proplot/issues/43"}