Skip to content

Capitalize headings in example Gallery #25017

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 19, 2023
Merged

Conversation

kolibril13
Copy link
Contributor

The headings in the example section are mostly upper case, but also a few lowercase headings::
image

This pr capitalizes all headings.

@oscargus
Copy link
Member

Thanks you for this PR! However, as those that you modified here are module names, I am not sure that they should be modified, at least not like this.

(Also, I think the style guide indicates that "Title Case" should not be used. https://matplotlib.org/stable/devel/documenting_mpl.html#formatting-and-style-conventions Rather "Specialty Plots" should probably be changed to "Specialty plots".)

I do agree with you though that the current approach looks a bit weird. Maybe one should format the modules as "code", so

``pyplot``
=======

etc, but not sure exactly what that would look like.

@oscargus
Copy link
Member

It is not clear what a "top-level chapter" is in

For everything but top-level chapters

but looking the current documentation it seems like there are no top-level chapters...

@kolibril13
Copy link
Contributor Author

I've now changed it to Upper lower.
For most example names in the gallery, there is the Title Case used.
image

Regarding module names: I think the style guide saies that "`" should not be used.
https://matplotlib.org/stable/devel/documenting_mpl.html#function-arguments

@anntzer
Copy link
Contributor

anntzer commented Jan 18, 2023

Please don't change the capitalization or remove underscores from module names (you can't import Pyplot or import Axes grid). If you want to make these more homogeneous, I would write e.g. The pyplot module/The axes_grid1 module.

@kolibril13
Copy link
Contributor Author

kolibril13 commented Jan 18, 2023

Please don't change the capitalization or remove underscores from module names

My changes are affecting the example gallery, so I thought that the example gallery captions should have names that describe to the users what examples to expect. Are the example gallery captions the right place for module names?
In my opinion no, but I am open to be convinced otherwise.

I think module names should only be used in the reference headings:
https://matplotlib.org/stable/api/toolkits/axes_grid1.html#mpl-toolkits-axes-grid1

you can't import Pyplot or import Axes grid

Yes, but so one can not do import Statistics from the Statistics section

@anntzer
Copy link
Contributor

anntzer commented Jan 18, 2023

Yes, but so one can not do import Statistics from the Statistics section

Indeed, but pyplot is nothing but a module name, whereas Statistics is obviously a common noun.
Anyways, I've made my point, I don't like the change here but other reviewers can disagree.

@oscargus
Copy link
Member

Just to confirm that what @anntzer maybe expressed clearer, is exactly what I was trying to say with the example. These are modules and should be spelled as the module, probably with some formatting to make it clear that it is a module.

Copy link
Member

@jklymak jklymak left a comment

Choose a reason for hiding this comment

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

Thanks for this, but I agree with @oscargus and @anntzer: the last one is fine, the rest are incorrect.

@kolibril13
Copy link
Contributor Author

Thanks for these very quick responses!

probably with some formatting to make it clear that it is a module

For consistency, I've now changed it to The axes_grid1 module , The axisartist module and The pyplot module

@QuLogic QuLogic added this to the v3.7.0 milestone Jan 19, 2023
@QuLogic QuLogic merged commit e12b75d into matplotlib:main Jan 19, 2023
meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Jan 19, 2023
oscargus added a commit that referenced this pull request Jan 19, 2023
…017-on-v3.7.x

Backport PR #25017 on branch v3.7.x (Capitalize headings in example Gallery)
@ksunden ksunden mentioned this pull request Feb 20, 2023
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants