René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[DOC/ENH] How to best handle repeating docstrings ","articleBody":"\u003c!--To help us understand and resolve your issue, please fill out the form to the best of your ability.--\u003e\r\n\u003c!--You can feel free to delete the sections that do not apply.--\u003e\r\n\r\n### Issue\r\n\r\nIn #9324 I refactored the docstrings for `legend.Legend.__init__`, `figure.Figure.legend` and `axes.Axes.legend`.  In particular, all three have the same kwargs because the two artist versions passthrough kwargs to `legend`.  All three had different and contradictory/incomplete docstrings.\r\n\r\nTo solve this, I used string interpolation.  The developer docs say:\r\n\r\n```\r\nSince matplotlib uses a lot of pass-through kwargs, e.g., in every function that creates \r\na line (plot(), semilogx(), semilogy(), etc…), it can be difficult for the new user to know which\r\nkwargs are supported. Matplotlib uses a docstring interpolation scheme to support \r\ndocumentation of every function that takes a **kwargs. \r\n```\r\n\r\nand the code has numerous places where this is used.   I used a simple form of this that hard-coded the kwarg doc string and then invoked it in the three docstrings:\r\n\r\n```python\r\n'''\r\nParameters\r\n-----------\r\n\r\n%(_legend_kw_doc)s\r\n'''\r\n```\r\n\r\nReviewers didn't like this (@NelleV, @anntzer, @tacaswell ) because apparently this sort of interpolation is fragile and has caused issues with the docs in the past:\r\n\r\n\u003e #7095, or http://matplotlib.org/2.0.0/api/_as_gen/matplotlib.axes.Axes.semilogy.html#matplotlib.axes.Axes.semilogy, are example of issues caused by uncontrolled interpolation.\r\n\r\nFor #9324 it was decided that we should just cut-and-paste the kwarg docs into the three docstrings.   I also implemented a test in `test_legend.py` that insured that the docstrings were the same to stop future drift of the docstrings.  \r\n\r\n### Proper solution?\r\n\r\nSo, what is the proper solution to the documentation problem of repeating passthrough kwargs?  I didn't see that the substitution decorator was so bad, but I've not seen all the problems.  \r\n\r\n#### Cut-and-paste:\r\n\r\nperhaps with unit tests to make sure the docstrings don't drift.\r\n\r\n#### Structure to hold docstrings:\r\n\r\n @anntzer suggested:\r\n\r\n\u003e  I think we should either use a proper (\"structured\") interpolation machinery or none at all.\r\n\r\ni.e., he suggested a \"structured\" docstring whereby each section is an `OrderedDict` entry, and each kwarg is an `OrderedDict` entry.  This allows referencing of this information in other docstrings.  [See below](https://github.com/matplotlib/matplotlib/issues/9414#issuecomment-336735095).  \r\n\r\n#### Functions to hold docstrings:\r\n\r\n@efiring [suggested](https://github.com/matplotlib/matplotlib/issues/9414#issuecomment-336742969) what is also essentially suggested in [MEP10](https://matplotlib.org/devel/MEP/MEP10.html) which is that specialized documentation functions be used that have the repeated kwargs, and then the main method's documentation references this.  \r\n\r\n### Documentation issue\r\n\r\nI think the developer docs should make the deprecation of the interpolation machinery explicit if it truly is deprecated.\r\n\r\n## Affected functions:\r\n\r\n - `figure.legend` = `axes.legend` = `legend.Legend`\r\n - colorbar?\r\n - text properties","author":{"url":"https://github.com/jklymak","@type":"Person","name":"jklymak"},"datePublished":"2017-10-15T18:46:34.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":28},"url":"https://github.com/9414/matplotlib/issues/9414"}