Review documentation of Axes plotting methods

As a follow up of #7205, some docstrings of the basic Axes plotting methods could need a bit care. In particular:

Conversion to numpydoc format.
Improvements on the descriptions.

I intend to go through the methods and update their docs. This is a summary issue to keep track of my progress:

Basic

Spans

Axes.axhline
Axes.axhspan
Axes.axvline
Axes.axvspan

Spectral

Statistics

Axes.boxplot
Axes.violinplot
Axes.violin
Axes.bxp

Binned

Axes.hexbin
Axes.hist
Axes.hist2d

Contours

Axes.clabel
Axes.contour
Axes.contourf

Array

Unstructured triangles

Axes.tripcolor
Axes.triplot
Axes.tricontour
Axes.tricontourf

Text and Annotations

Axes.annotate
Axes.text
Axes.table
Axes.arrow

Fields

Axes.barbs
Axes.quiver
Axes.quiverkey
Axes.streamplot

Axes limits and direction

Axes scales

Axes.get_xscale
Axes.set_xscale
Axes.get_yscale
Axes.set_yscale

Note: I currently update the docstrings in my private branch https://github.com/timhoffm/matplotlib/tree/axes-plotting-docstrings and will provide a pull request once I'm done. I think this is better than opening a separate pull request for every change. Please let me know, in case you'd rather prefer many smaller PRs.

The fixes will be supplied in a series of PRs referencing this issue.

I think the only disadvantage to a big PR is you may have to privately rebase a bunch, and other folks might make conflicting changes if it takes you a while.

I would probably make PR with small batches of related methods, but one-at-a-time is fine too.
A giant PR is also fine as long as you don't mind an unbounded (in time...) review process.

Thanks for the answers. I'll switch to smaller batches then.

I think it would be really great if the documentation of a function could link to some (or all?) examples from the gallery that use this function.
I don't know at which point this would be specified, if it's in the docstring or some sphinx config file?
Also linking from the examples to the docs is only present in some cases.

There is some of that on a few of the pages: https://matplotlib.org/api/_as_gen/matplotlib.patches.Wedge.html#matplotlib.patches.Wedge

I have no idea from looking at the source how that happens, however.

BTW, I like the doc interpolation, but not when someone has named the doscstring something unsearchable like Patch. Does anyone know where the Patch docstring lives that is interpolated via %(Patch)s?

... or is it just auto-generating from the set_ and get_?

Yeah, that's exactly what I mean.
In the page source it says

 .. include:: matplotlib.patches.Wedge.examples

but the question is indeed who is reponsible for putting that line there?

The %(Patch)s seems to come from

matplotlib/lib/matplotlib/patches.py

Lines 551 to 558 in d54e2e3

    
           patchdoc = artist.kwdoc(Patch) 
        
           for k in ('Rectangle', 'Circle', 'RegularPolygon', 'Polygon', 'Wedge', 'Arrow', 
        
                     'FancyArrow', 'YAArrow', 'CirclePolygon', 'Ellipse', 'Arc', 
        
                     'FancyBboxPatch', 'Patch'): 
        
               docstring.interpd.update({k: patchdoc}) 
        
           # define Patch.__init__ docstring after the class has been added to interpd 
        
           docstring.dedent_interpd(Patch.__init__)

Which then points to

matplotlib/lib/matplotlib/artist.py

Line 1466 in d54e2e3

def kwdoc(a):

and that seems to indeed give the setters from the classes. But I don't think it will help with creating the examples, or will it?

Opening new issue

I'm explicitly excluding work on gallery links from this effort. It's already big enough as it is now. The gallery links have their own ticket #10974.

Improve docstring of triplot() and PatchCollection

Rework tricontour and tricontourf documentation

Improve docstring of triplot() and PatchCollection

Rework tricontour and tricontourf documentation

Improve docstring of triplot() and PatchCollection

Rework tricontour and tricontourf documentation

Navigation Menu

Repository navigation

Review documentation of Axes plotting methods #10148

Basic

Spans

Spectral

Statistics

Binned

Contours

Array

Unstructured triangles

Text and Annotations

Fields

Axes limits and direction

Axes scales

2 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	patchdoc = artist.kwdoc(Patch)
	for k in ('Rectangle', 'Circle', 'RegularPolygon', 'Polygon', 'Wedge', 'Arrow',
	'FancyArrow', 'YAArrow', 'CirclePolygon', 'Ellipse', 'Arc',
	'FancyBboxPatch', 'Patch'):
	docstring.interpd.update({k: patchdoc})

	# define Patch.__init__ docstring after the class has been added to interpd
	docstring.dedent_interpd(Patch.__init__)

Review documentation of Axes plotting methods #10148

Description

Basic

Spans

Spectral

Statistics

Binned

Contours

Array

Unstructured triangles

Text and Annotations

Fields

Axes limits and direction

Axes scales

Activity

jklymak commented on Jan 3, 2018

anntzer commented on Jan 3, 2018

timhoffm commented on Jan 3, 2018

ImportanceOfBeingErnest commented on Apr 6, 2018

jklymak commented on Apr 6, 2018

jklymak commented on Apr 6, 2018

jklymak commented on Apr 6, 2018

ImportanceOfBeingErnest commented on Apr 6, 2018

jklymak commented on Apr 6, 2018

timhoffm commented on Apr 6, 2018

2 remaining items

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions