Skip to content
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.

Sign up for GitHub

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

Jump to bottom

MNT: re-organize galleries under one subdir #25209

Merged
merged 1 commit into from
Feb 24, 2023
Merged

MNT: re-organize galleries under one subdir #25209

merged 1 commit into from
Feb 24, 2023

Conversation

jklymak
Copy link
Member

@jklymak jklymak commented Feb 14, 2023 •
edited
Loading

PR Summary

This reorganizes all the galleries (examples, tutorials, plot_types) under one subdirectory. Also renames examples->gallery so that it is the same name as the gallery it makes.

So now sphinx-gallery looks in /galleries/gallery, /galleries/tutorials/ and /galleries/plot_types.

The goal here is that now that sphinx-gallery/sphinx-gallery#1071 is in, we may have more subdirectories run through sphinx gallery (perhaps many more), and it pollutes the top-level file hierarchy to have a bunch of these.

Note that no examples were changed by this, and there should be no difference on the doc page (except in the "writing Documentation" page where the file names have changed).

PR Checklist

Documentation and Tests

  • Has pytest style unit tests (and pytest passes)
  • Documentation is sphinx and numpydoc compliant (the docs should build without error).
  • New plotting related features are documented with examples.

Release Notes

  • New features are marked with a .. versionadded:: directive in the docstring and documented in doc/users/next_whats_new/
  • API changes are marked with a .. versionchanged:: directive in the docstring and documented in doc/api/next_api_changes/
  • Release notes conform with instructions in next_whats_new/README.rst or next_api_changes/README.rst

jklymak
jklymak commented Feb 14, 2023
View reviewed changes
doc/devel/documenting_mpl.rst
files in :file:`plot_types/`, :file:`examples/` and :file:`tutorials/`.
These sources consist of python scripts that have ReST_ documentation built
into their comments. See :ref:`writing-examples-and-tutorials` below.
:file:`doc/tutorials` are generated by the `Sphinx Gallery`_ from python files
Copy link
Member Author

Choose a reason for hiding this comment

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

This file is the only user-facing change.

@jklymak jklymak force-pushed the mnt-reorg-galleries branch from 004c5cc to 87da4d5 Compare February 14, 2023 06:25
@tacaswell tacaswell added this to the v3.8.0 milestone Feb 14, 2023
@tacaswell
Copy link
Member

👍🏻 in principle.

@jklymak jklymak force-pushed the mnt-reorg-galleries branch 3 times, most recently from 416364c to 7fcc80a Compare February 14, 2023 16:57
@jklymak jklymak marked this pull request as ready for review February 14, 2023 17:29
@jklymak jklymak mentioned this pull request Feb 14, 2023
Closed
6 tasks
@timhoffm
Copy link
Member

"examples" is a better name than "gallery", because it's more semantic (also galleries/Gallery is awkward). Can we go the other way and add a http redirect from gallery to example to preserve existing links working, so that we can use "example" consistently.

@jklymak
Copy link
Member Author

jklymak commented Feb 15, 2023

The change here just makes the private name the same as the public. I'm not sure if there is a mechanism to change the public name. If there is, changing the private is just a one-line "git mv" and a few edit in the dev docs and the conf.py.

We could also keep the private and public names different (that was not really the point here) but I think it is needlessly confusing.

@timhoffm
Copy link
Member

We could also keep the private and public names different

Slight preference for doing this if you want to move forward without going into "changing the public name" right now. Having "gallery" as the internal name and url, but resulting in a page titled "Examples" which is under the menu entry "Examples" is still confusing. The only consistent naming option is all "examples".

@jklymak jklymak mentioned this pull request Feb 20, 2023
Merged
6 tasks
@jklymak jklymak force-pushed the mnt-reorg-galleries branch from 7fcc80a to 20eda30 Compare February 20, 2023 16:36
@jklymak
Copy link
Member Author

jklymak commented Feb 20, 2023

The structure is now galleries/examples -> doc/gallery. Redirecting doc/gallery -> doc/examples via http redirect requires getting into the setup mechanisms for our web host

@ksunden
Copy link
Member

ksunden commented Feb 21, 2023

Unfortunately #25270 conflicted the animation examples (and a couple README's)... should be relatively trivial (probably for all of the animation ones at least it is the grammatical change from generate to generated on the note about the html viewer that was made on the backport.)

Also, am I misremembering the call? I thought the conclusion of that conversation was that we preferred the term "examples" over "gallery" for the repo paths (and desired doing redirects to make the url match as "examples", rather than its current "gallery", though I can acknowledge that much may be out of scope for now).

The extra level of heirarchy is fine, and I don't mind that being called "galleries", but for those called "examples" now, keeping it so was my impression of the consensus.

@jklymak jklymak force-pushed the mnt-reorg-galleries branch from 20eda30 to 69cc6a1 Compare February 21, 2023 21:05
@jklymak
Copy link
Member Author

jklymak commented Feb 21, 2023

Sorry, I somehow messed up the last push.

@jklymak jklymak force-pushed the mnt-reorg-galleries branch 2 times, most recently from 03197dc to c5c7eeb Compare February 22, 2023 18:30
@jklymak jklymak marked this pull request as draft February 22, 2023 18:30
@jklymak jklymak force-pushed the mnt-reorg-galleries branch from c5c7eeb to cca402e Compare February 22, 2023 18:50
@jklymak jklymak marked this pull request as ready for review February 22, 2023 19:54
@jklymak jklymak force-pushed the mnt-reorg-galleries branch from cca402e to c1fad31 Compare February 22, 2023 22:15
@QuLogic
Copy link
Member

QuLogic commented Feb 23, 2023

It looks like .github/workflows/tests.yml, .gitignore, .pre-commit-config.yaml and pyproject.toml need updating.

@jklymak jklymak force-pushed the mnt-reorg-galleries branch from c1fad31 to ddc4079 Compare February 23, 2023 04:28
@jklymak
Copy link
Member Author

jklymak commented Feb 23, 2023

It looks like .github/workflows/tests.yml, .gitignore, .pre-commit-config.yaml and pyproject.toml need updating.

Phew, we sure repeat the same exceptions in a lot of places....

@jklymak jklymak force-pushed the mnt-reorg-galleries branch from ddc4079 to 01cc2ca Compare February 23, 2023 15:29
@jklymak
Copy link
Member Author

jklymak commented Feb 23, 2023

The pre-commit isort block doesn't hit galleries/plot_types. I didn't fix that because that directory fails isort, and didn't want to sidetrack this...

@jklymak jklymak force-pushed the mnt-reorg-galleries branch from 01cc2ca to 853b3f9 Compare February 23, 2023 20:07
QuLogic
QuLogic reviewed Feb 23, 2023
View reviewed changes
.gitignore Outdated Show resolved Hide resolved
.gitignore Outdated Show resolved Hide resolved
@jklymak jklymak force-pushed the mnt-reorg-galleries branch from 853b3f9 to fe53160 Compare February 23, 2023 20:33
@QuLogic QuLogic merged commit c630505 into matplotlib:main Feb 24, 2023
@jklymak
Copy link
Member Author

jklymak commented Feb 24, 2023

Thanks for everyone's patient reviews...

@jklymak jklymak deleted the mnt-reorg-galleries branch February 24, 2023 01:34
@ksunden ksunden mentioned this pull request Mar 17, 2023
Merged
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@QuLogic QuLogic QuLogic approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
v3.8.0
Development

Successfully merging this pull request may close these issues.
5 participants
@jklymak @tacaswell @timhoffm @ksunden @QuLogic