Skip to content

Establish draft Tag glossary and Tagging guidelines #26851

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

Merged
merged 15 commits into from
Oct 31, 2023
Merged

Establish draft Tag glossary and Tagging guidelines #26851

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
1a3b32f
tag guideline draft
esibinga Aug 4, 2023
86672af
carriage breaks
esibinga Sep 21, 2023
af6366e
tabs
esibinga Sep 21, 2023
c87995e
indentation
esibinga Sep 21, 2023
c289586
styling changes and Melissa's suggested changes
esibinga Oct 6, 2023
ad4dee2
changes to level and purpose
esibinga Oct 27, 2023
2ae0421
Apply suggestions from code review
esibinga Oct 27, 2023
b6d2641
Apply suggestions from code review
esibinga Oct 29, 2023
ed45c85
Apply suggestions from code review
esibinga Oct 29, 2023
71f25f4
move docs back to devel, updates from review
esibinga Oct 30, 2023
00ba10d
Apply suggestions from code review
esibinga Oct 30, 2023
87261c1
clarify component and styling
esibinga Oct 30, 2023
c45922b
updates from review
esibinga Oct 30, 2023
afa15c4
Apply suggestions from code review
esibinga Oct 31, 2023
8326b51
add template for new tag proposal issues
esibinga Oct 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .github/ISSUE_TEMPLATE/tag_proposal.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
name: Tag Proposal
description: Suggest a new tag or subcategory for the gallery of examples
title: "[Tag]: "
labels: [Tag proposal]
body:
- type: markdown
attributes:
value: |
Please search the [tag glossary]() for relevant tags before creating a new tag proposal.
- type: textarea
id: need
attributes:
label: Need
description: Briefly describe the need this tag will fill. (1-4 sentences)
placeholder: |
* A tag is needed for examples that share [...]
* Existing tags do not work because [...]
* Current gallery examples that would use this tag include [...]
* Indicate which subcategory this tag falls under, or whether a new subcategory is proposed.
validations:
required: true
- type: textarea
id: solution
attributes:
label: Proposed solution
description: What should the tag be? All tags are in the format `subcategory: tag`
1 change: 1 addition & 0 deletions doc/devel/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@ Policies and guidelines

document
style_guide
tag_guidelines

.. grid-item-card::
:shadow: none
Expand Down
181 changes: 181 additions & 0 deletions doc/devel/tag_glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
:orphan:

Tag Glossary
============

I. API tags: what content from the API reference is in the example?
II. Structural tags: what format is the example? What context can we provide?
III. Domain tags: what discipline(s) might seek this example consistently?
IV. Internal tags: what information is helpful for maintainers or contributors?


API tags: what content from the API reference is in the example?
----------------------------------------------------------------

+-----------------------------------+---------------------------------------------+
|``tag`` | use case - if not obvious |
+===================================+=============================================+
|**Primary or relevant plot component** |
+-----------------------------------+---------------------------------------------+
|``component: axes`` |remarkable or very clear use of component |
+-----------------------------------+---------------------------------------------+
|``component: axis`` | |
+-----------------------------------+---------------------------------------------+
|``component: marker`` | |
+-----------------------------------+---------------------------------------------+
|``component: label`` | |
+-----------------------------------+---------------------------------------------+
|``component: title`` | |
+-----------------------------------+---------------------------------------------+
|``component: legend`` | |
+-----------------------------------+---------------------------------------------+
|``component: subplot`` | |
+-----------------------------------+---------------------------------------------+
|``component: figure`` | |
+-----------------------------------+---------------------------------------------+
|``component: annotation`` | |
+-----------------------------------+---------------------------------------------+
|``component: label`` | |
+-----------------------------------+---------------------------------------------+
|``component: ticks`` | |
+-----------------------------------+---------------------------------------------+
|``component: spines`` |frequently paired with ``component: axis`` |
+-----------------------------------+---------------------------------------------+
|``component: error`` | |
+-----------------------------------+---------------------------------------------+
|``component: animation`` | |
+-----------------------------------+---------------------------------------------+
| | |
+-----------------------------------+---------------------------------------------+
|**Styling** |
+-----------------------------------+---------------------------------------------+
|Use these tags when plot contains a teachable example |
+-----------------------------------+---------------------------------------------+
|``styling: color`` | |
+-----------------------------------+---------------------------------------------+
|``styling: shape`` | |
+-----------------------------------+---------------------------------------------+
|``styling: size`` | |
+-----------------------------------+---------------------------------------------+
|``styling: position`` | |
+-----------------------------------+---------------------------------------------+
|``styling: texture`` | |
+-----------------------------------+---------------------------------------------+
|``styling: colormap`` | |
+-----------------------------------+---------------------------------------------+
|``styling: linestyle`` | |
+-----------------------------------+---------------------------------------------+
|``styling: small-multiples`` | |
+-----------------------------------+---------------------------------------------+
|``styling: conditional`` |styling is determined programmatically by a |
| |condition being met |
+-----------------------------------+---------------------------------------------+
| | |
+-----------------------------------+---------------------------------------------+
|**Interactivity** |
+-----------------------------------+---------------------------------------------+
|``interactivity: event handling`` | |
+-----------------------------------+---------------------------------------------+
|``interactivity: click`` | |
+-----------------------------------+---------------------------------------------+
|``interactivity: mouseover`` | |
+-----------------------------------+---------------------------------------------+
|``interactivity: zoom`` | |
+-----------------------------------+---------------------------------------------+
|``interactivity: pan`` | |
+-----------------------------------+---------------------------------------------+
|``interactivity: brush`` | |
+-----------------------------------+---------------------------------------------+
|``interactivity: drag`` | |
+-----------------------------------+---------------------------------------------+
|``interactivity: scroll`` | |
+-----------------------------------+---------------------------------------------+
| | |
+-----------------------------------+---------------------------------------------+
|**Plot Type** |
+-----------------------------------+---------------------------------------------+
|``plot type: bar`` |example contains a bar plot |
+-----------------------------------+---------------------------------------------+
|``plot type: line`` |example contains a line plot |
+-----------------------------------+---------------------------------------------+
|``plot type: pie`` |example contains a pie plot |
+-----------------------------------+---------------------------------------------+
|``plot type: polar`` |example contains a polar plot |
+-----------------------------------+---------------------------------------------+
|``plot type: 3D`` |example contains a 3D plot |
+-----------------------------------+---------------------------------------------+
|``plot type: histogram`` |example contains a histogram |
+-----------------------------------+---------------------------------------------+
|``plot type: specialty`` | |
+-----------------------------------+---------------------------------------------+
|``plot type: scatter`` | |
+-----------------------------------+---------------------------------------------+


Structural tags: what format is the example? What context can we provide?
-------------------------------------------------------------------------

+----------------------------+-------------------------------------------------------------------+
|``tag`` | use case |
+============================+===================================================================+
|``level`` |level refers to how much context/background the user will need |
+----------------------------+-------------------------------------------------------------------+
|``level: beginner`` |concepts are standalone, self-contained, require only one module |
+----------------------------+-------------------------------------------------------------------+
|``level: intermediate`` |concepts may require knowledge of other modules, have dependencies |
+----------------------------+-------------------------------------------------------------------+
|``level: advanced`` |concepts require multiple modules and have dependencies |
+----------------------------+-------------------------------------------------------------------+
|``purpose`` |what's it here for? |
+----------------------------+-------------------------------------------------------------------+
|``purpose: storytelling`` |storytelling exemplar -- build a visual argument |
+----------------------------+-------------------------------------------------------------------+
|``purpose: reference`` |reference docs like "marker reference" or "list of named colors" |
| | - dense collection of short-format information |
| | - well-defined scope, accessible information |
+----------------------------+-------------------------------------------------------------------+
|``purpose: fun`` |just for fun! |
+----------------------------+-------------------------------------------------------------------+
|``purpose: showcase`` |good showcase example |
+----------------------------+-------------------------------------------------------------------+

Domain tags: what discipline(s) might seek this example consistently?
---------------------------------------------------------------------

It's futile to draw fences around "who owns what", and that's not the point of domain tags. Domain tags help groups of people to privately organize relevant information, and so are not displayed publicly. See below for a list of existing domain tags. If you don't see the one you're looking for and you think it should exist, consider proposing it.

+-------------------------------+----------------------------------------+
|``tag`` | use case |
+===============================+========================================+
|``domain`` |for whom is the example relevant? |
+-------------------------------+----------------------------------------+
|``domain: cartography`` | |
+-------------------------------+----------------------------------------+
|``domain: geometry`` | |
+-------------------------------+----------------------------------------+
|``domain: statistics`` | |
+-------------------------------+----------------------------------------+
|``domain: oceanography`` | |
+-------------------------------+----------------------------------------+
|``domain: signal-processing`` | |
+-------------------------------+----------------------------------------+

Internal tags: what information is helpful for maintainers or contributors?
---------------------------------------------------------------------------

+-------------------------------+-----------------------------------------------------------------------+
|``tag`` | use case |
+===============================+=======================================================================+
|``internal: low bandwidth`` |allows users to filter out bandwidth-intensive examples like animations|
Copy link
Member

Choose a reason for hiding this comment

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

If that is the intent then should we tag the minority (high bandwith) examples instead?

+-------------------------------+-----------------------------------------------------------------------+
|``internal: untagged`` |allows docs contributors to easily find untagged examples |
Copy link
Member

Choose a reason for hiding this comment

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

wouldn't it be easier to search for files that do not have the tag directive?

+-------------------------------+-----------------------------------------------------------------------+
|``internal: deprecated`` |examples containing deprecated functionality or concepts |
+-------------------------------+-----------------------------------------------------------------------+
|``internal: needs-review`` |example needs to be reviewed for accuracy or pedagogical value |
+-------------------------------+-----------------------------------------------------------------------+
|``internal: outstanding-todo`` |example has an unfinished to-do |
+-------------------------------+-----------------------------------------------------------------------+
|``internal: too-much`` |the example should be refined, split into multiple examples, or |
| |reformatted into a tutorial or reference |
+-------------------------------+-----------------------------------------------------------------------+
75 changes: 75 additions & 0 deletions doc/devel/tag_guidelines.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
Guidelines for assigning tags to gallery examples
=================================================

Why do we need tags?
--------------------

Tags serve multiple purposes.

Tags have a one-to-many organization (i.e. one example can have several tags), while the gallery structure requires that examples are placed in only one location. This means tags provide a secondary layer of organization and make the gallery of examples more flexible and more user-friendly.

They allow for better discoverability, search, and browse functionality. They are helpful for users struggling to write a search query for what they're looking for.

Hidden tags provide additional functionality for maintainers and contributors.

What gets a tag?
----------------

Every gallery example should be tagged with:

* 1+ content tags
* structural, domain, or internal tag(s) if helpful

Tags can repeat existing forms of organization (e.g. an example is in the Animation folder and also gets an ``animation`` tag).

Tags are helpful to denote particularly good "byproduct" examples. E.g. the explicit purpose of a gallery example might be to demonstrate a colormap, but it's also a good demonstration of a legend. Tag ``legend`` to indicate that, rather than changing the title or the scope of the example.

**Tag Categories** - See :doc:`Tag Glossary <tag_glossary>` for a complete list of tags.

I. API tags: what content from the API reference is in the example?
II. Structural tags: what format is the example? What context can we provide?
III. Domain tags: what discipline(s) might seek this example consistently?
IV. Internal tags: what information is helpful for maintainers or contributors?

Proposing new tags
------------------

1. Review existing tag list, looking out for similar entries (i.e. ``axes`` and ``axis``).
2. If a relevant tag or subcategory does not yet exist, propose it. Each tag is two parts: ``subcategory: tag``. Tags should be one or two words.
Copy link
Member

Choose a reason for hiding this comment

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

add the "how to propose" process list?

3. New tags should be be added when they are relevant to existing gallery entries too. Avoid tags that will link to only a single gallery entry.
4. Tags can recreate other forms of organization.

Note: Tagging organization aims to work for 80-90% of cases. Some examples fall outside of the tagging structure. Niche or specific examples shouldn't be given standalone tags that won't apply to other examples.

How to tag?
-----------
Put each tag as a directive at the bottom of the page.
Copy link
Member

Choose a reason for hiding this comment

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

include an example in this text?


Related content
---------------

What is a gallery example?
^^^^^^^^^^^^^^^^^^^^^^^^^^

The gallery of examples contains visual demonstrations of matplotlib features. Gallery examples exist so that users can scan through visual examples.

Unlike tutorials or user guides, gallery examples teach by demonstration, rather than by explanation or instruction.

Gallery examples should avoid instruction or excessive explanation except for brief clarifying code comments. Instead, they can tag related concepts and/or link to relevant tutorials or user guides.

Format
^^^^^^

All :ref:`examples-index` should aim to follow the following format:

* Title: 1-6 words, descriptive of content
* Subtitle: 10-50 words, action-oriented description of the example subject
* Image: a clear demonstration of the subject, showing edge cases and different applications if possible
* Code + Text (optional): code, commented as appropriate + written text to add context if necessary

Example:

The ``bbox_intersect`` gallery example demonstrates the point of visual examples:

* this example is "messy" in that it's hard to categorize, but the gallery is the right spot for it because it makes sense to find it by visual search
* https://matplotlib.org/devdocs/gallery/misc/bbox_intersect.html#sphx-glr-gallery-misc-bbox-intersect-py