Changes to the pyplot api documentation #11620

fredrik-1 · 2018-07-10T19:52:45Z

I did some formatting to the pyplot api page. The sections are mostly taken from the sections in the pyplot.py file.

I took away the colormaps section as it is a function in pyplot anyway.

These changes make it much easier to find out about the pyplot functions.

Has Pytest style unit tests
Code is PEP 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

ImportanceOfBeingErnest · 2018-07-10T20:11:27Z

doc/api/pyplot_api.rst

+    autoscale
+    axhline
+    axhspan
+    axis


Those are no plotting functions: axis, cla, grid, sci, polar, xlabel, ylabel, set_cmap, title, xscale, yscale etc.

Ok, thats true. They are in the plotting section of pyplot though and I haven't look through that part in much detail.

ImportanceOfBeingErnest · 2018-07-10T20:17:25Z

Are you proposing to delete the "Colors" section? Or where would you put it instead?

fredrik-1 · 2018-07-10T20:28:12Z

The color section where mostly the docstring for the pyplot.colormap function and I think that the section can be taken away. I don't think that it should be explicitly in the pyplot api anyway.

One possibility if a section with that name should exist somewhere due to links is to put it on its own page in the api list.

ImportanceOfBeingErnest · 2018-07-10T20:31:39Z

Yes that was already the idea in the last PR. But simply deleting it is not an option.

fredrik-1 · 2018-07-10T21:20:38Z

I took out the non plotting functions from the plotting functions. I hope I got it mostly correct.

About the color section. I thought that the discussion in that pr was mostly about other things.

The only part I delete in this PR is

There are many colormaps you can use to map data onto color values. Below we list several ways in which color can be utilized in Matplotlib.

For a more in-depth look at colormaps, see the Colormaps in Matplotlib tutorial.

The rest is in pyplot.colormaps that is linked to on the pyplot_api page.

The problems I see with my approach.

It is possible that there are links to the old section in the documentation.
It might be good to have that information in an easy to find place.

I am not sure of either of these two problems but I don't see how that section could have been linked and there are already acm (colormaps)and a colors section on the api page.

I can look through the information that exist today and propose a solution.

tacaswell · 2018-07-10T21:39:01Z

I have a preference for keeping this content in the file pyplot_summary because that name ends up as part of the URL so by making the same change we will be breaking peoples bookmarks (and making the mixed version in the top-level docs problem worse).

tacaswell · 2018-07-10T21:41:43Z

I am very 👍 on the overall idea and the organization!

timhoffm

Thanks! This is a great improvement.

I'm pondering if we should group the functions a bit differently, e.g. put all the image functions together. But that could still be done later on if desired.

timhoffm · 2018-07-10T22:49:53Z

doc/api/pyplot_api.rst

+    setp
+    xkcd
+
+Making figures


"Creating figures" is the more common term.

timhoffm · 2018-07-10T22:58:46Z

doc/api/pyplot_api.rst

+
+.. currentmodule:: matplotlib.pyplot
+
+.. automodule:: matplotlib.pyplot


The module description is a bit out of place now. It should probably be a one-sentence description and reference the pyplot API section in API overview and maybe the pyplot tutorial.

A discussion vs the OOP approach and an example are unnecessary here.

timhoffm · 2018-07-10T23:02:36Z

doc/api/pyplot_api.rst

+    :template: autosummary.rst
+    :nosignatures:
+
+    getp


getp does not link because it does not live in pyplot. It's just imported. Can we do something about this?

timhoffm · 2018-07-10T23:05:25Z

doc/api/pyplot_api.rst

+    savefig
+    waitforbuttonpress
+
+Putting things in figures


Sound a bit clumsy. Maybe "Adding elements to figures"?

timhoffm · 2018-07-10T23:05:53Z

doc/api/pyplot_api.rst

+    sci
+    set_cmap
+
+Putting things in axes


Adding elements to axes?

timhoffm · 2018-07-10T23:07:01Z

doc/api/pyplot_api.rst

+    figtext
+    suptitle
+
+Working with axes


Should this be capital "Axes"?

Possibly as well in other headlines?

dstansby · 2018-07-11T20:07:16Z

Old: https://matplotlib.org/devdocs/api/pyplot_summary.html
New: https://11480-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/api/pyplot_summary.html

(for anyone else who wants to review)

dstansby

This looks so much better, thanks a lot 👍 . I have a few small comments, which I've put inline.

dstansby · 2018-07-11T20:09:12Z

doc/api/pyplot_summary.rst


+Any artist


What does this mean? Functions that can be used by any artist? Or functions that are applied to every artist on the plot?

They are functions that can be applied to every artist. The name was just taken from thepyplot file.

dstansby · 2018-07-11T20:10:15Z

doc/api/pyplot_summary.rst


-For a more in-depth look at colormaps, see the
-:doc:`/tutorials/colors/colormaps` tutorial.
+Making figures


I would say this should be moved to the top, since this is the one bit of the pyplots stuff everyone has to use even if they then use the object oriented API.

And it's the first thing to do in a plot 😄

Generally, I would roughly sort the sections by how often a typical user may need them. While on the other hand, keeping related topics together. e.g. putting things in figures either next to putting things in axes or next to working with figures.

By the way, do you want to stick to the putting things wording?

dstansby · 2018-07-11T20:11:06Z

doc/api/pyplot_summary.rst

+
+Working with axes
+=================
+


Might be worth putting a single sentence here saying what an axes is (as opposed to an axis)

dstansby · 2018-07-11T20:11:15Z

doc/api/pyplot_summary.rst

+
+Working with axis
+=================
+


Might be worth putting a single sentence here saying what an axis is (as opposed to an axes)

dstansby · 2018-07-11T20:11:44Z

doc/api/pyplot_summary.rst

+
+Current image
+=============
+


Current image doesn't mean much to me, might be worth putting a single sentence here too.

dstansby · 2018-07-11T20:12:23Z

doc/api/pyplot_summary.rst

+    imread
+    imsave
+
+Plotting functions


Might be worth moving this up too, since these are probably the second most common set of functions that people use.

fredrik-1 · 2018-07-18T21:37:53Z

I finally did some changes.

I kind of like the ordering in pyplot_summary in large. I think that the most important pyplot functions are the ones for creating figures, the global functions and the ones for any artist. The rest are not really necessary.

I looked through the color documentation and I think that the docstring in pyplot.colormaps are an old version of the colormap tutorial. I don't think that it is good to have similar documentation at different places so I deleted a large part of the docstring.

I made the links to the two most important color tutorials on the color_api page explicit.

It was not clearly documented that the matplotlib.cm module has a dictionary with all colormaps or that every colormap is an attribute to the module. I tried to write that in the module docstring as a numpydoc docstring but it didn't work for some reason.

new version

jklymak · 2021-04-15T17:51:04Z

@fredrik-1 Thanks so much for your efforts with the docs. This is really out of date, so I'm going to close, but please feel free to rebase if you think there are helpful changes to the current docs in here... Sorry this didn't get over the line!

ImportanceOfBeingErnest reviewed Jul 10, 2018

View reviewed changes

fredrik-1 force-pushed the pyplot_api branch 2 times, most recently from 44bd036 to db07723 Compare July 10, 2018 21:03

tacaswell added this to the v2.2-doc milestone Jul 10, 2018

dstansby added the Documentation label Jul 10, 2018

timhoffm reviewed Jul 10, 2018

View reviewed changes

fredrik-1 force-pushed the pyplot_api branch from db07723 to a082b48 Compare July 11, 2018 07:18

dstansby reviewed Jul 11, 2018

View reviewed changes

fredrik-1 force-pushed the pyplot_api branch 3 times, most recently from aaf0652 to 2bc5466 Compare July 18, 2018 21:15

pyplot api docs changes

8806c2e

fredrik-1 force-pushed the pyplot_api branch from 2bc5466 to 8806c2e Compare July 18, 2018 21:41

jklymak closed this Apr 15, 2021


		.. currentmodule:: matplotlib.pyplot

		.. automodule:: matplotlib.pyplot


		Any artist


		Working with axes
		=================


		Working with axis
		=================

Uh oh!

Changes to the pyplot api documentation #11620

Changes to the pyplot api documentation #11620

Uh oh!

Conversation

fredrik-1 commented Jul 10, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ImportanceOfBeingErnest commented Jul 10, 2018

Uh oh!

fredrik-1 commented Jul 10, 2018

Uh oh!

ImportanceOfBeingErnest commented Jul 10, 2018

Uh oh!

fredrik-1 commented Jul 10, 2018

Uh oh!

tacaswell commented Jul 10, 2018

Uh oh!

tacaswell commented Jul 10, 2018

Uh oh!

timhoffm left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dstansby commented Jul 11, 2018

Uh oh!

dstansby left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm Jul 11, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fredrik-1 commented Jul 18, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jklymak commented Apr 15, 2021

Uh oh!

Uh oh!

timhoffm left a comment •

edited

Loading

timhoffm Jul 11, 2018 •

edited

Loading

fredrik-1 commented Jul 18, 2018 •

edited

Loading