GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — DOC: Standardize example titles - part 2 by timhoffm · Pull Request #28641 · matplotlib/matplotlib

Conversation

timhoffm commented Aug 1, 2024

Copy link

Copy Markdown

Member

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

github-actions Bot added the Documentation: examples files in galleries/examples label

Aug 1, 2024

timhoffm commented

Aug 1, 2024

View reviewed changes

Comment thread

galleries/examples/lines_bars_and_markers/fill_between_alpha.py

		Fill Between with transparency
		==============================
		==================================
		``fill_between`` with transparency

timhoffm Aug 1, 2024 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

story645 reacted with thumbs up emoji

All reactions

👍 1 reaction

story645 Aug 1, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

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

story645 left a comment

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for putting in easy to review on phone PRs 😅

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

galleries/examples/axes_grid1/demo_colorbar_with_inset_locator.py Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread

galleries/examples/lines_bars_and_markers/fill_between_demo.py Outdated

		Filling the area between lines
		==============================
		===========================
		Fill the area between lines

story645 Aug 2, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

	Fill the area between lines
	Fill area between horizontal curves

Mostly to draw distinction between fill_betweenx,

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

timhoffm Aug 2, 2024

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

galleries/examples/lines_bars_and_markers/fill_betweenx_demo.py Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread

galleries/examples/misc/bbox_intersect.py Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread

galleries/examples/misc/fig_x.py Outdated

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

story645 Aug 2, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

timhoffm Aug 2, 2024

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

galleries/examples/user_interfaces/embedding_in_gtk3_panzoom_sgskip.py

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

story645 Aug 2, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

galleries/examples/user_interfaces/embedding_in_gtk4_panzoom_sgskip.py

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

story645 Aug 2, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

galleries/examples/user_interfaces/embedding_in_gtk4_sgskip.py

		Embedding in GTK4
		=================
		=============
		Embed in GTK4

story645 Aug 2, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

galleries/examples/user_interfaces/embedding_in_wx2_sgskip.py

		Embedding in wx #2
		==================
		==============
		Embed in wx #2

story645 Aug 2, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

galleries/examples/user_interfaces/embedding_in_wx5_sgskip.py

		Embedding in wx #5
		==================
		==============
		Embed in wx #5

story645 Aug 2, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can all the wx be combined?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

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

timhoffm commented Aug 2, 2024

Copy link

Copy Markdown

Member Author

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

story645 reacted with thumbs up emoji

All reactions

👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

story645 approved these changes

Aug 2, 2024

View reviewed changes

story645 left a comment

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

galleries/examples/lines_bars_and_markers/fill_betweenx_demo.py Outdated

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

story645 Aug 2, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

galleries/examples/misc/fig_x.py Outdated

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

story645 Aug 2, 2024

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions


          DOC: Standardize example titles - part 2

a4e9e07

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 <[email protected]>

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

Reviewers

story645

story645 approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

Documentation: examples

files in galleries/examples

Projects

None yet

Milestone

v3.10.0

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

2 participants

Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

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

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

timhoffm Aug 1, 2024 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.