DOC: Support dynamic filtering by tags for gallery examples with Sphinx-Gallery v0.21.0

[seisman]

Sphinx-Gallery v0.21.0 introduces tag support for gallery examples, which allows examples to be tagged and filtered more effectively. See https://sphinx-gallery.github.io/stable/configuration.html#tagging-examples-and-filtering for the usage and https://sphinx-gallery.github.io/stable/auto_examples/index.html?#general-examples for a live demo.

This feature would be very beneficial for the PyGMT gallery, which has grown substantially and can be difficult to navigate, especially for new users. Tag support would allow:

• Better discoverability of examples
• More flexible navigation
• Easier onboarding for new users
• Improved documentation structure without major reorganization

Potential checklist

• Decide if we want to support tags
• Decide on the list of allowed tags for PyGMT
• Document the list of allowed tags
• Upgrade to Sphinx-Gallery ≥ 0.21.0
• Add tags to gallery examples using the new tagging mechanism [definitely in multiple PRs]
• See if we should reorganize the structure of the gallery
• Update contributing guides

[Chuan1937]

Sure, we should add tags. Such as:

Tag	Description
maps	Maps and map elements
lines	Lines and curves
symbols	Symbols and markers
images	Images and grids
3d	3D plots
seismology	Seismology
basemaps	Basemaps (dual y-axis, ternary, etc.)
histograms	Histograms and rose diagrams
embellishments	Embellishments (colorbars, legends, etc.)
projections	Map projections
beginner	Beginner-friendly
advanced	Advanced

[yvonnefroehlich]

I agree that adding tags will make it easier to navigate through the examples.

But I am still debating on the concept we should use for the labels. I believe it's not really helpful to use more or less the subsections we currently have also as labels. I am wondering if we can (additionally) have labels similar to the AGU24 workshop. Maybe we can have a look at the label concept used by matplotlib as inspiration.

[Chuan1937]

AGU24 workshop is good

[seisman]

The AGU24 workshop uses labels based on module names, but I don’t think we need to add similar labels here.

Such labels are mainly useful for finding examples that use a specific module, and we already provide that functionality on the API page for each module wrapper. For example, the examples using coast are already listed on the pygmt.Figure.coast API page.

[weiji14]

I believe it's not really helpful to use more or less the subsections we currently have also as labels. I am wondering if we can (additionally) have labels similar to the AGU24 workshop.

I also think the Gallery Page is pretty well organized already by the subsections. Maybe we should start by adding tags for the Tutorial page at https://www.pygmt.org/v0.18.0/tutorials/index.html or the Projections page at https://www.pygmt.org/v0.18.0/projections/index.html instead?

Personally I would like it if we can filter the Projections page by attributes such as:

• equal-area (preserve correct area)
• equidistant (preserve true distances)
• conformal (preserve angles)

Maybe start with these projection properties that are not so controversial, and then we can expand tags to other pages later?