DOC: Add links to explicit vs implicit API everywhere "OO" is used #22613

tacaswell · 2022-03-06T21:21:02Z

PR Summary

I search for every use of "object-oriented" in the code base and make sure they all had some reference to the https://matplotlib.org/devdocs/users/explain/api_interfaces.html

$ ack 'object[- ]oriented'
doc/api/index.rst
125:At its core, Matplotlib is an object-oriented library. We recommend directly
138:- Most of the :ref:`examples <examples-index>` use the object-oriented approach

doc/users/explain/api_interfaces.rst
11:  been called an "object-oriented" interface.

doc/users/prev_whats_new/changelog.rst
1264:    object-oriented and pylab interfaces. It is now strictly object-oriented -

doc/users/prev_whats_new/github_stats_3.1.1.rst
177:* :ghissue:`1219`: Show fails on figures created with the object-oriented system

doc/users/prev_whats_new/github_stats_3.5.0.rst
418:* :ghpull:`21132`: Backport PR #21093 on branch v3.5.x (DOC: clarify what we mean by object oriented in pyplot api)
422:* :ghpull:`21093`: DOC: clarify what we mean by object oriented in pyplot api
627:* :ghpull:`20792`: Change legend guide to object oriented approach

doc/users/project/history.rst
14:independent of MATLAB, and can be used in a Pythonic, object-oriented

examples/misc/pythonic_matplotlib.py
6:Some people prefer to write more "Pythonic", explicitly object-oriented code

examples/text_labels_and_annotations/fonts_demo.py
3:Fonts demo (object-oriented style)

lib/matplotlib/__init__.py
2:An object-oriented plotting library.
20:For the most part, direct use of the explicit object-oriented library is

lib/matplotlib/pyplot.py
19:The explicit object-oriented API is recommended for complex plots, though

tutorials/introductory/lifecycle.py
26:The first is an explicit object-oriented (OO) interface. In this case, we
81:# group. To do this with the object-oriented approach, we first generate

tutorials/introductory/pyplot.py
306:# stateful wrapper around an object-oriented API, which you can use

tutorials/introductory/quick_start.py
143:#   "object-oriented (OO) style").

PR Checklist

Tests and Styling

[N/A] Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (install flake8-docstrings and run flake8 --docstring-convention=all).

Documentation

[/] New features are documented, with examples if plot related.
[/] New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
[/] API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).
Documentation is sphinx and numpydoc compliant (the docs should build without error).

Closes matplotlib#18249

greglucas

👍 Overall looks good to me, mostly just suggestions for tightening up "single space after a period" and "trade-off" with a dash.

greglucas · 2022-03-07T02:15:37Z

doc/api/index.rst

@@ -114,10 +114,33 @@ Alphabetical list of modules:
 Usage patterns
 --------------

-Below we describe several common approaches to plotting with Matplotlib.
+Below we describe several common approaches to plotting with Matplotlib.  See


Suggested change

Below we describe several common approaches to plotting with Matplotlib. See

Below we describe several common approaches to plotting with Matplotlib. See

doc/api/index.rst

greglucas · 2022-03-07T02:40:23Z

tutorials/introductory/lifecycle.py

+The first is an explicit object-oriented (OO) interface. In this case, we
+utilize an instance of :class:`axes.Axes` in order to render visualizations on
+an instance of :class:`figure.Figure`.  The second is based on MATLAB and uses


This seems a bit jargony with the use of "render" here. My assumption for the audience is someone pretty new to MPL and interested in "plotting", "visualizing", and "showing" not necessarily rendering. So, perhaps one of those words instead here?

tutorials/introductory/pyplot.py

greglucas · 2022-03-07T02:41:48Z

tutorials/introductory/pyplot.py

-# in a figure, plots some lines in a plotting area, decorates the plot
-# with labels, etc.
+# :mod:`matplotlib.pyplot` is a collection of functions that make matplotlib
+# work like MATLAB.  Each ``pyplot`` function makes some change to a figure:


Suggested change

# work like MATLAB. Each ``pyplot`` function makes some change to a figure:

# work like MATLAB. Each ``pyplot`` function makes some change to a figure:

tutorials/introductory/pyplot.py

greglucas · 2022-03-07T02:43:40Z

tutorials/introductory/pyplot.py

-#    from an ``Axes`` object. We recommend browsing the tutorials and
-#    examples to see how this works.
+#    the implicit pyplot API is generally terser but less-flexible than the
+#    explicit API.  Most of the function calls you see here can also be called


Suggested change

# explicit API. Most of the function calls you see here can also be called

# explicit API. Most of the function calls you see here can also be called

Co-authored-by: Greg Lucas <greg.m.lucas@gmail.com>

examples/subplots_axes_and_figures/multiple_figs_demo.py

Looks like it was rendering as definition list due to the extra indenting.

Co-authored-by: Oscar Gustafsson <oscar.gustafsson@gmail.com>

tacaswell · 2022-03-07T18:03:10Z

I am not sure how I feel about the 1 space vs 2 space. I think we have a mix in the documentation and I prefer 2 spaces and tend to write that way, but if people feel very strongly we should document it.

greglucas · 2022-03-07T18:25:42Z

I'm pretty firmly in the "one space" camp, but won't block over it at all. I mostly just prefer consistency over anything else. I think all style-guides now suggest one space.
https://www.masterclass.com/articles/how-many-spaces-after-a-period#6-style-guides-that-recommend-a-single-space

greglucas

Interestingly enough, it looks like the final page's html actually only has one space after a period, so I guess the extra whitespace is somehow gobbled up somewhere along the path.

I just noticed that the list of Modules on the API reference page is quite long and pushes the explicit/implicit discussion to the bottom. So, maybe swap the order and put the long list of modules to the bottom of that page instead to bring the interface discussion up higher?

tacaswell · 2022-03-22T04:32:07Z

I looked at replacing all "" in the repo and it touches over 500 files.....

DOC: Add links to explicit vs implicit API everywhere "OO" is used

512a006

Closes matplotlib#18249

tacaswell added the Documentation label Mar 6, 2022

tacaswell added this to the v3.6.0 milestone Mar 6, 2022

greglucas reviewed Mar 7, 2022

View reviewed changes

tacaswell and others added 2 commits March 7, 2022 10:05

DOC: fix typos / wording

fe424c5

Co-authored-by: Greg Lucas <greg.m.lucas@gmail.com>

DOC: fix wording

8c06764

Co-authored-by: Greg Lucas <greg.m.lucas@gmail.com>

oscargus reviewed Mar 7, 2022

View reviewed changes

examples/subplots_axes_and_figures/multiple_figs_demo.py Outdated Show resolved Hide resolved

DOC: fix formatting of bullet list

19c9011

Looks like it was rendering as definition list due to the extra indenting.

tacaswell force-pushed the doc_oo_to_explicit branch from ff17886 to c1df30e Compare March 7, 2022 16:51

DOC: fix line wrapping

c1df30e

Co-authored-by: Oscar Gustafsson <oscar.gustafsson@gmail.com>

greglucas approved these changes Mar 11, 2022

View reviewed changes

tacaswell added 2 commits March 22, 2022 00:12

DOC: move module listing to bottom of api index page

7c96ed0

DOC: reword top of lifecycle tutorial

7083aba

greglucas merged commit a436253 into matplotlib:main Apr 8, 2022

tacaswell deleted the doc_oo_to_explicit branch April 9, 2022 18:08

rcomer mentioned this pull request Nov 17, 2023

Clarify that it is ok to use plt.subplots to create figures #19554

Closed

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Add links to explicit vs implicit API everywhere "OO" is used #22613

DOC: Add links to explicit vs implicit API everywhere "OO" is used #22613

tacaswell commented Mar 6, 2022

greglucas left a comment

greglucas Mar 7, 2022

greglucas Mar 7, 2022

greglucas Mar 7, 2022

greglucas Mar 7, 2022

tacaswell commented Mar 7, 2022

greglucas commented Mar 7, 2022

greglucas left a comment

tacaswell commented Mar 22, 2022

	Below we describe several common approaches to plotting with Matplotlib. See
	Below we describe several common approaches to plotting with Matplotlib. See

	# work like MATLAB. Each ``pyplot`` function makes some change to a figure:
	# work like MATLAB. Each ``pyplot`` function makes some change to a figure:

	# explicit API. Most of the function calls you see here can also be called
	# explicit API. Most of the function calls you see here can also be called

DOC: Add links to explicit vs implicit API everywhere "OO" is used #22613

DOC: Add links to explicit vs implicit API everywhere "OO" is used #22613

Conversation

tacaswell commented Mar 6, 2022

PR Summary

PR Checklist

greglucas left a comment

Choose a reason for hiding this comment

greglucas Mar 7, 2022

Choose a reason for hiding this comment

greglucas Mar 7, 2022

Choose a reason for hiding this comment

greglucas Mar 7, 2022

Choose a reason for hiding this comment

greglucas Mar 7, 2022

Choose a reason for hiding this comment

tacaswell commented Mar 7, 2022

greglucas commented Mar 7, 2022

greglucas left a comment

Choose a reason for hiding this comment

tacaswell commented Mar 22, 2022