Reorganize gallery examples #995

willschlitzer · 2021-03-03T06:50:44Z

This pull request reorganizes the gallery examples to have more specific categories.

Fixes #876

Reminders

Run make format and make check to make sure the code follows the style guide.
Add tests for new features or tests that would have caught the bug that you're fixing.
Add new public functions/methods/classes to doc/api/index.rst.
Write detailed docstrings for all functions/methods.
If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

/format: automatically format and lint the code
/test-gmt-dev: run full tests on the latest GMT development version

seisman · 2021-03-03T15:34:06Z

@willschlitzer Thanks for opening the PR. It would be much easier to discuss how we want to group gallery examples by viewing what any new designs look like.

To make it work, you also need to update the following lines in doc/conf.py:

pygmt/doc/conf.py

Lines 72 to 85 in 55c6176

    
           "subsection_order": ExplicitOrder( 
        
               [ 
        
                   "../examples/gallery/line", 
        
                   "../examples/gallery/coast", 
        
                   "../examples/gallery/plot", 
        
                   "../examples/gallery/grid", 
        
                   "../examples/projections/azim", 
        
                   "../examples/projections/conic", 
        
                   "../examples/projections/cyl", 
        
                   "../examples/projections/misc", 
        
                   "../examples/projections/nongeo", 
        
                   "../examples/projections/table", 
        
               ] 
        
           ),

.

seisman · 2021-03-04T15:46:27Z

Ping @GenericMappingTools/python @GenericMappingTools/python-maintainers for comments.

maxrjones · 2021-03-04T15:53:01Z

Looks great! Based on #967 and the great response to @liamtoney's ROSES tutorial, I hope we can eventually have a whole seismology gallery section!

seisman · 2021-03-04T17:09:22Z

Perhaps rename the directory gallery/line to gallery/lines?

…ize-gallery

examples/gallery/line/README.txt

weiji14 · 2021-03-05T01:49:42Z

Kinda unrelated, but can we rename one of the inset.py files, one which is for the gallery and one for the tutorial, because there is a warning message:

`WARNING: Duplicate example file name(s) found. Having duplicate file names will break some links. List of files: ['../examples/tutorials/inset.py']

core-man · 2021-03-05T05:31:41Z

Looks great～

Do Colorbar and Legend only belong to Map and map elements? But I've no better category for them. Shall we add a category called Additional figure elements or Unclarified?

There is a category called Images, symbols, and markers. Shall we move Images to an individual category? If yes, which ones are images in the current category, Images or EPS files on maps?

By the way, shall we rename this gallery to something like Images or EPS files on figures since we can put them on any figure instead of only a map, right?

Referring to #876 (comment) and #876 (comment), how about the following content for the current galleries?

Maps and map elements
Lines and vectors
Symbols and markers
Images and contours (NEW)
3D plots
Additional figure elements or Unclarified (NEW)

seisman · 2021-03-05T06:16:38Z

There is a category called Images, symbols, and markers. Shall we move Images to an individual category? If yes, which ones are images in the current category, Images or EPS files on maps?

I agree we should have a separate category for images. As I commented in #876, I think the category name could be "Images and contours" or "Images, contours and fields", like matplotlib (https://matplotlib.org/stable/gallery/index.html#images-contours-and-fields).

By the way, shall we rename this gallery to something like Images or EPS files on figures since we can put them on any figure instead of only a map, right?

Sounds good. Actually, Figure.image() can recognize most image formats (png, jpg, eps, pdf et al.) via GDAL. So I think we could just say "Put images on figures" or similar.

core-man · 2021-03-05T06:30:07Z

Can we control the figure order in each category? For example, in Maps and map elements gallery, the order is now: Political Boundaries, Colorbar, Inset, ..., Sampling along tracks. It seems that we can have a better order so that some related examples can be put together, e.g., Political Boundaries, Color land and water, Shorelines seem related to each other.

willschlitzer · 2021-03-05T07:54:03Z

Kinda unrelated, but can we rename one of the inset.py files, one which is for the gallery and one for the tutorial, because there is a warning message:
`WARNING: Duplicate example file name(s) found. Having duplicate file names will break some links. List of files: ['../examples/tutorials/inset.py']

Done in 965dbf3

seisman · 2021-03-05T16:46:20Z

Can we control the figure order in each category? For example, in Maps and map elements gallery, the order is now: Political Boundaries, Colorbar, Inset, ..., Sampling along tracks. It seems that we can have a better order so that some related examples can be put together, e.g., Political Boundaries, Color land and water, Shorelines seem related to each other.

There are different ways to sort the examples in one section (see https://sphinx-gallery.github.io/stable/configuration.html#within-gallery-order).
Currently, they are sorted by file names, but perhaps it makes more sense to sort by Title (ExampleTitleSortKey)?

pygmt/doc/conf.py

Line 91 in ffe0c2a

"within_subsection_order": FileNameSortKey,

seisman · 2021-03-11T17:09:47Z

I just pushed a few changes to this branch:

f953632: Rename two python files using underscores
e0e507d + ce706f4: Rename "inset-tutorial.py" to "insets.py"
f6622f8: Fix broken references due to recent renamings
e3c8c10: Rename the directory "3d-plots" to "3d_plots" (also use underscores for directories)

seisman

This PR now looks good to me.

Ping @GenericMappingTools/python @GenericMappingTools/python-contributors
@GenericMappingTools/python-maintainers for comments and approvals.

maxrjones

Nice!

michaelgrund

Looks good! No further suggestions.

core-man · 2021-03-11T17:56:47Z

Great~

willschlitzer · 2021-03-11T18:26:01Z

@weiji14 Can you confirm that you are no longer requesting changes?

seisman · 2021-03-12T04:40:37Z

Ping @weiji14 to give this PR a final review.

weiji14

Oops, thanks for the ping. Juggling too much on my plate recently (handling a release on another Python package and uni stuff). Just one comment.

examples/gallery/images/README.txt

Changes in this PR: - Reorganizes the gallery examples to have more specific categories - Sort gallery examples by "title" in each subsection - Use underscores in file and directory names Co-authored-by: Dongdong Tian <seisman.info@gmail.com> Co-authored-by: Michael Grund <michael_grund@gmx.de> Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> Co-authored-by: Yao Jiayuan <coreman.seism@gmail.com> Co-authored-by: Meghan Jones <meghanj@hawaii.edu>

Reorganize gallery examples

8473c69

willschlitzer added this to the 0.3.1 milestone Mar 3, 2021

willschlitzer added the documentation Improvements or additions to documentation label Mar 3, 2021

Merge branch 'master' into reorganize-gallery

b63a481

vercel bot temporarily deployed to Preview March 3, 2021 06:53 Inactive

Update conf.py

8ba8cb0

vercel bot temporarily deployed to Preview March 3, 2021 20:26 Inactive

Merge branch 'master' into reorganize-gallery

77e377f

vercel bot temporarily deployed to Preview March 3, 2021 21:17 Inactive

willschlitzer added 2 commits March 4, 2021 19:41

Changing "line" to "lines"

c4ab089

Merge remote-tracking branch 'origin/reorganize-gallery' into reorgan…

f7c2d3c

…ize-gallery

vercel bot temporarily deployed to Preview March 4, 2021 19:41 Inactive

seisman reviewed Mar 5, 2021

View reviewed changes

examples/gallery/line/README.txt Outdated Show resolved Hide resolved

Rename folder from "line" to "lines"

3639b50

vercel bot temporarily deployed to Preview March 5, 2021 07:52 Inactive

Rename inset.py tutorial example to inset-tutorial.py

965dbf3

Merge branch 'master' into reorganize-gallery

642d9c2

vercel bot temporarily deployed to Preview March 5, 2021 08:01 Inactive

weiji14 mentioned this pull request Mar 7, 2021

Improve PyGMT documentation #996

Closed

5 tasks

Change sort for gallery

5ebef74

Merge branch 'master' into reorganize-gallery

b78b9e8

vercel bot temporarily deployed to Preview March 11, 2021 06:59 Inactive

vercel bot temporarily deployed to Preview March 11, 2021 07:14 Inactive

vercel bot temporarily deployed to Preview March 11, 2021 15:24 Inactive

seisman added 4 commits March 11, 2021 10:40

Rename two files using underscores

f953632

Rename inset-tutorial.py to insets.py

e0e507d

Update references in examples

f6622f8

Rename 3d-plots to 3d_plots

e3c8c10

vercel bot temporarily deployed to Preview March 11, 2021 17:07 Inactive

Fix a broken reference to inset.py

ce706f4

vercel bot temporarily deployed to Preview March 11, 2021 17:18 Inactive

seisman approved these changes Mar 11, 2021

View reviewed changes

maxrjones approved these changes Mar 11, 2021

View reviewed changes

michaelgrund approved these changes Mar 11, 2021

View reviewed changes

core-man approved these changes Mar 11, 2021

View reviewed changes

weiji14 reviewed Mar 12, 2021

View reviewed changes

examples/gallery/images/README.txt Show resolved Hide resolved

weiji14 approved these changes Mar 12, 2021

View reviewed changes

Merge branch 'master' into reorganize-gallery

a3c54aa

vercel bot temporarily deployed to Preview March 12, 2021 05:06 Inactive

seisman merged commit b2b3d1f into master Mar 12, 2021

seisman deleted the reorganize-gallery branch March 12, 2021 05:13

core-man mentioned this pull request Mar 13, 2021

Update the title for the images/EPS on maps gallery example #1052

Merged

5 tasks

This was referenced Mar 14, 2021

Changelog entry for v0.3.1 release #1047

Merged

Release PyGMT v0.3.1 #987

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reorganize gallery examples #995

Reorganize gallery examples #995

willschlitzer commented Mar 3, 2021

seisman commented Mar 3, 2021

seisman commented Mar 4, 2021

maxrjones commented Mar 4, 2021

seisman commented Mar 4, 2021 •

edited

Loading

weiji14 commented Mar 5, 2021

core-man commented Mar 5, 2021 •

edited

Loading

seisman commented Mar 5, 2021

core-man commented Mar 5, 2021 •

edited

Loading

willschlitzer commented Mar 5, 2021

seisman commented Mar 5, 2021

seisman commented Mar 11, 2021 •

edited

Loading

seisman left a comment

maxrjones left a comment

michaelgrund left a comment

core-man commented Mar 11, 2021

willschlitzer commented Mar 11, 2021

seisman commented Mar 12, 2021

weiji14 left a comment

Reorganize gallery examples #995

Reorganize gallery examples #995

Conversation

willschlitzer commented Mar 3, 2021

seisman commented Mar 3, 2021

seisman commented Mar 4, 2021

maxrjones commented Mar 4, 2021

seisman commented Mar 4, 2021 • edited Loading

weiji14 commented Mar 5, 2021

core-man commented Mar 5, 2021 • edited Loading

seisman commented Mar 5, 2021

core-man commented Mar 5, 2021 • edited Loading

willschlitzer commented Mar 5, 2021

seisman commented Mar 5, 2021

seisman commented Mar 11, 2021 • edited Loading

seisman left a comment

Choose a reason for hiding this comment

maxrjones left a comment

Choose a reason for hiding this comment

michaelgrund left a comment

Choose a reason for hiding this comment

core-man commented Mar 11, 2021

willschlitzer commented Mar 11, 2021

seisman commented Mar 12, 2021

weiji14 left a comment

Choose a reason for hiding this comment

seisman commented Mar 4, 2021 •

edited

Loading

core-man commented Mar 5, 2021 •

edited

Loading

core-man commented Mar 5, 2021 •

edited

Loading

seisman commented Mar 11, 2021 •

edited

Loading