DOC: Standardize example titles - part 2 by timhoffm · Pull Request #28641 · matplotlib/matplotlib

timhoffm · 2024-08-01T22:11:37Z

Follow up to #28544. As there:

Following recommendations from #28527, this improves example titles. Take this as an incremental improvement. I've changed what I saw at a glance when going through the examples once. Certainly, one could do further improvements, but that can be done in follow-ups.

timhoffm · 2024-08-01T22:14:07Z

galleries/examples/lines_bars_and_markers/fill_between_alpha.py

-Fill Between with transparency
-==============================
+==================================
+``fill_between`` with transparency


So far, there's only one case of formatting example titles (plt.subplots). I feel it's slightly better to format function names as literal rather than just have them as plain text. But no strong opinion. We can also leave out the formatting if desired.

If sphinx doesn't complain, I fully support formatting function names this way

story645

Thanks for putting in easy to review on phone PRs 😅

galleries/examples/axes_grid1/demo_colorbar_with_inset_locator.py

story645 · 2024-08-02T01:29:23Z

galleries/examples/lines_bars_and_markers/fill_between_demo.py

-Filling the area between lines
-==============================
+===========================
+Fill the area between lines


Suggested change

Fill the area between lines

Fill area between horizontal curves

Mostly to draw distinction between fill_betweenx,

I've kept the title (only adding "two"): "Fill the area between two lines"

While the docstring says "horizontal curves" and I've changed fill_betweenx to "Fill the area between vertical curves", I like the simplicity of "lines". This alludes to Line2D. The term "horizontal curve" insinuates precision, but is acutally still vague.

What "horizontal curve" actually means, are two curves that are defined at the same horizontal positions x. Visually, the lines can be quite non-horizontal. But I'm unable to express this in the title, so I stick to the very generic description, which I believe will catch people intuitively.

galleries/examples/lines_bars_and_markers/fill_betweenx_demo.py

galleries/examples/misc/bbox_intersect.py

story645 · 2024-08-02T01:40:34Z

galleries/examples/misc/fig_x.py

-Adding lines to figures
-=======================
+=====================
+Add lines to a figure


Suggested change

Add lines to a figure

Draw lines without an axes

The "no axes" part isn't implied by the title and is I think the important part.

The point is really "to a figure" not "without an axes".

Getting a bit out of scope, but small enough to not make a separate PR: I've changed the content of the example to something more practical:

story645 · 2024-08-02T01:59:02Z

galleries/examples/user_interfaces/embedding_in_gtk3_panzoom_sgskip.py

-Embedding in GTK3 with a navigation toolbar
-===========================================
+=======================================
+Embed in GTK3 with a navigation toolbar


Suggested change

Embed in GTK3 with a navigation toolbar

Embed plot with a navigation toolbar in GTK3

I think here it might be better to have the subject

story645 · 2024-08-02T02:00:02Z

galleries/examples/user_interfaces/embedding_in_gtk4_panzoom_sgskip.py

-Embedding in GTK4 with a navigation toolbar
-===========================================
+=======================================
+Embed in GTK4 with a navigation toolbar


Same as 3, also do we want this as one example (embed in GTK) and then maybe tab GTK3 and GTK4 or have them as subheadings?

story645 · 2024-08-02T02:00:44Z

galleries/examples/user_interfaces/embedding_in_gtk4_sgskip.py

-Embedding in GTK4
-=================
+=============
+Embed in GTK4


Same, do we want one GTK example and then the diff versions as subheadings?

story645 · 2024-08-02T02:01:22Z

galleries/examples/user_interfaces/embedding_in_wx2_sgskip.py

-Embedding in wx #2
-==================
+==============
+Embed in wx #2


Why wx #2 when it's wxagg in text?

story645 · 2024-08-02T02:01:43Z

galleries/examples/user_interfaces/embedding_in_wx5_sgskip.py

-Embedding in wx #5
-==================
+==============
+Embed in wx #5


Can all the wx be combined?

timhoffm · 2024-08-02T08:18:02Z

I leave all the embed stuff for now. That should be resturctured in a separate PR.

story645

slight grammar consistency nits, can self merge after fixing those.

story645 · 2024-08-02T17:03:12Z

galleries/examples/lines_bars_and_markers/fill_betweenx_demo.py

-Fill Betweenx Demo
-==================
+=========================================
+Fill the area between two vertical curves


Suggested change

Fill the area between two vertical curves

Fill the area between two vertical lines

since you like lines better, since the terminology should stay consistent across both. I'm not sure if I think this example should be combined w/ the other one.

story645 · 2024-08-02T17:06:56Z

galleries/examples/misc/fig_x.py

-Adding lines to figures
-=======================
+=================================
+Add lines to directly to a figure


Suggested change

Add lines to directly to a figure

Add lines directly to a figure

grammar nit,

and my qualm/concern is folks not understanding what "to a figure" means, but the more I unpack that the more I'm thinking it probably can't be solved in a title

Follow up to matplotlib#28544. As there: Following recommendations from matplotlib#28527, this improves example titles. Take this as an incremental improvement. I've changed what I saw t a glance when going through the examples once. Certainly, one could do further improvements, but that can be done in follow-ups. Co-authored-by: hannah <story645@gmail.com>

github-actions bot added the Documentation: examples files in galleries/examples label Aug 1, 2024

timhoffm commented Aug 1, 2024

View reviewed changes

timhoffm force-pushed the doc-example-titles branch 3 times, most recently from af9f872 to c6cf03f Compare August 1, 2024 22:47

story645 reviewed Aug 2, 2024

View reviewed changes

timhoffm closed this Aug 2, 2024

timhoffm deleted the doc-example-titles branch August 2, 2024 07:38

timhoffm restored the doc-example-titles branch August 2, 2024 07:41

timhoffm reopened this Aug 2, 2024

timhoffm force-pushed the doc-example-titles branch from c6cf03f to 5cf1437 Compare August 2, 2024 08:01

story645 approved these changes Aug 2, 2024

View reviewed changes

timhoffm force-pushed the doc-example-titles branch from 5cf1437 to a4e9e07 Compare August 2, 2024 20:30

timhoffm added this to the v3.10.0 milestone Aug 2, 2024

timhoffm merged commit c17197c into matplotlib:main Aug 2, 2024

timhoffm deleted the doc-example-titles branch August 2, 2024 20:45

	Fill the area between lines
	Fill area between horizontal curves

	Embed in GTK3 with a navigation toolbar
	Embed plot with a navigation toolbar in GTK3

	Fill the area between two vertical curves
	Fill the area between two vertical lines

	Add lines to directly to a figure
	Add lines directly to a figure

Uh oh!

Conversation

timhoffm commented Aug 1, 2024

Uh oh!

timhoffm Aug 1, 2024 • 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!

story645 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

timhoffm commented Aug 2, 2024

Uh oh!

story645 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

timhoffm Aug 1, 2024 •

edited

Loading