Skip to content

Commit 05ea428

Browse files
story645story645
authored
Merge pull request matplotlib#26851 from esibinga/tag-guidelines
Establish draft Tag glossary and Tagging guidelines
2 parents 1335730 + 8326b51 commit 05ea428

File tree

4 files changed

+283
-0
lines changed

4 files changed

+283
-0
lines changed

‎.github/ISSUE_TEMPLATE/tag_proposal.yml

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Tag Proposal
2+
description: Suggest a new tag or subcategory for the gallery of examples
3+
title: "[Tag]: "
4+
labels: [Tag proposal]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Please search the [tag glossary]() for relevant tags before creating a new tag proposal.
10+
- type: textarea
11+
id: need
12+
attributes:
13+
label: Need
14+
description: Briefly describe the need this tag will fill. (1-4 sentences)
15+
placeholder: |
16+
* A tag is needed for examples that share [...]
17+
* Existing tags do not work because [...]
18+
* Current gallery examples that would use this tag include [...]
19+
* Indicate which subcategory this tag falls under, or whether a new subcategory is proposed.
20+
validations:
21+
required: true
22+
- type: textarea
23+
id: solution
24+
attributes:
25+
label: Proposed solution
26+
description: What should the tag be? All tags are in the format `subcategory: tag`

‎doc/devel/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,7 @@ Policies and guidelines
146146

147147
document
148148
style_guide
149+
tag_guidelines
149150

150151
.. grid-item-card::
151152
:shadow: none

‎doc/devel/tag_glossary.rst

+181
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
:orphan:
2+
3+
Tag Glossary
4+
============
5+
6+
I. API tags: what content from the API reference is in the example?
7+
II. Structural tags: what format is the example? What context can we provide?
8+
III. Domain tags: what discipline(s) might seek this example consistently?
9+
IV. Internal tags: what information is helpful for maintainers or contributors?
10+
11+
12+
API tags: what content from the API reference is in the example?
13+
----------------------------------------------------------------
14+
15+
+-----------------------------------+---------------------------------------------+
16+
|``tag`` | use case - if not obvious |
17+
+===================================+=============================================+
18+
|**Primary or relevant plot component** |
19+
+-----------------------------------+---------------------------------------------+
20+
|``component: axes`` |remarkable or very clear use of component |
21+
+-----------------------------------+---------------------------------------------+
22+
|``component: axis`` | |
23+
+-----------------------------------+---------------------------------------------+
24+
|``component: marker`` | |
25+
+-----------------------------------+---------------------------------------------+
26+
|``component: label`` | |
27+
+-----------------------------------+---------------------------------------------+
28+
|``component: title`` | |
29+
+-----------------------------------+---------------------------------------------+
30+
|``component: legend`` | |
31+
+-----------------------------------+---------------------------------------------+
32+
|``component: subplot`` | |
33+
+-----------------------------------+---------------------------------------------+
34+
|``component: figure`` | |
35+
+-----------------------------------+---------------------------------------------+
36+
|``component: annotation`` | |
37+
+-----------------------------------+---------------------------------------------+
38+
|``component: label`` | |
39+
+-----------------------------------+---------------------------------------------+
40+
|``component: ticks`` | |
41+
+-----------------------------------+---------------------------------------------+
42+
|``component: spines`` |frequently paired with ``component: axis`` |
43+
+-----------------------------------+---------------------------------------------+
44+
|``component: error`` | |
45+
+-----------------------------------+---------------------------------------------+
46+
|``component: animation`` | |
47+
+-----------------------------------+---------------------------------------------+
48+
| | |
49+
+-----------------------------------+---------------------------------------------+
50+
|**Styling** |
51+
+-----------------------------------+---------------------------------------------+
52+
|Use these tags when plot contains a teachable example |
53+
+-----------------------------------+---------------------------------------------+
54+
|``styling: color`` | |
55+
+-----------------------------------+---------------------------------------------+
56+
|``styling: shape`` | |
57+
+-----------------------------------+---------------------------------------------+
58+
|``styling: size`` | |
59+
+-----------------------------------+---------------------------------------------+
60+
|``styling: position`` | |
61+
+-----------------------------------+---------------------------------------------+
62+
|``styling: texture`` | |
63+
+-----------------------------------+---------------------------------------------+
64+
|``styling: colormap`` | |
65+
+-----------------------------------+---------------------------------------------+
66+
|``styling: linestyle`` | |
67+
+-----------------------------------+---------------------------------------------+
68+
|``styling: small-multiples`` | |
69+
+-----------------------------------+---------------------------------------------+
70+
|``styling: conditional`` |styling is determined programmatically by a |
71+
| |condition being met |
72+
+-----------------------------------+---------------------------------------------+
73+
| | |
74+
+-----------------------------------+---------------------------------------------+
75+
|**Interactivity** |
76+
+-----------------------------------+---------------------------------------------+
77+
|``interactivity: event handling`` | |
78+
+-----------------------------------+---------------------------------------------+
79+
|``interactivity: click`` | |
80+
+-----------------------------------+---------------------------------------------+
81+
|``interactivity: mouseover`` | |
82+
+-----------------------------------+---------------------------------------------+
83+
|``interactivity: zoom`` | |
84+
+-----------------------------------+---------------------------------------------+
85+
|``interactivity: pan`` | |
86+
+-----------------------------------+---------------------------------------------+
87+
|``interactivity: brush`` | |
88+
+-----------------------------------+---------------------------------------------+
89+
|``interactivity: drag`` | |
90+
+-----------------------------------+---------------------------------------------+
91+
|``interactivity: scroll`` | |
92+
+-----------------------------------+---------------------------------------------+
93+
| | |
94+
+-----------------------------------+---------------------------------------------+
95+
|**Plot Type** |
96+
+-----------------------------------+---------------------------------------------+
97+
|``plot type: bar`` |example contains a bar plot |
98+
+-----------------------------------+---------------------------------------------+
99+
|``plot type: line`` |example contains a line plot |
100+
+-----------------------------------+---------------------------------------------+
101+
|``plot type: pie`` |example contains a pie plot |
102+
+-----------------------------------+---------------------------------------------+
103+
|``plot type: polar`` |example contains a polar plot |
104+
+-----------------------------------+---------------------------------------------+
105+
|``plot type: 3D`` |example contains a 3D plot |
106+
+-----------------------------------+---------------------------------------------+
107+
|``plot type: histogram`` |example contains a histogram |
108+
+-----------------------------------+---------------------------------------------+
109+
|``plot type: specialty`` | |
110+
+-----------------------------------+---------------------------------------------+
111+
|``plot type: scatter`` | |
112+
+-----------------------------------+---------------------------------------------+
113+
114+
115+
Structural tags: what format is the example? What context can we provide?
116+
-------------------------------------------------------------------------
117+
118+
+----------------------------+-------------------------------------------------------------------+
119+
|``tag`` | use case |
120+
+============================+===================================================================+
121+
|``level`` |level refers to how much context/background the user will need |
122+
+----------------------------+-------------------------------------------------------------------+
123+
|``level: beginner`` |concepts are standalone, self-contained, require only one module |
124+
+----------------------------+-------------------------------------------------------------------+
125+
|``level: intermediate`` |concepts may require knowledge of other modules, have dependencies |
126+
+----------------------------+-------------------------------------------------------------------+
127+
|``level: advanced`` |concepts require multiple modules and have dependencies |
128+
+----------------------------+-------------------------------------------------------------------+
129+
|``purpose`` |what's it here for? |
130+
+----------------------------+-------------------------------------------------------------------+
131+
|``purpose: storytelling`` |storytelling exemplar -- build a visual argument |
132+
+----------------------------+-------------------------------------------------------------------+
133+
|``purpose: reference`` |reference docs like "marker reference" or "list of named colors" |
134+
| | - dense collection of short-format information |
135+
| | - well-defined scope, accessible information |
136+
+----------------------------+-------------------------------------------------------------------+
137+
|``purpose: fun`` |just for fun! |
138+
+----------------------------+-------------------------------------------------------------------+
139+
|``purpose: showcase`` |good showcase example |
140+
+----------------------------+-------------------------------------------------------------------+
141+
142+
Domain tags: what discipline(s) might seek this example consistently?
143+
---------------------------------------------------------------------
144+
145+
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.
146+
147+
+-------------------------------+----------------------------------------+
148+
|``tag`` | use case |
149+
+===============================+========================================+
150+
|``domain`` |for whom is the example relevant? |
151+
+-------------------------------+----------------------------------------+
152+
|``domain: cartography`` | |
153+
+-------------------------------+----------------------------------------+
154+
|``domain: geometry`` | |
155+
+-------------------------------+----------------------------------------+
156+
|``domain: statistics`` | |
157+
+-------------------------------+----------------------------------------+
158+
|``domain: oceanography`` | |
159+
+-------------------------------+----------------------------------------+
160+
|``domain: signal-processing`` | |
161+
+-------------------------------+----------------------------------------+
162+
163+
Internal tags: what information is helpful for maintainers or contributors?
164+
---------------------------------------------------------------------------
165+
166+
+-------------------------------+-----------------------------------------------------------------------+
167+
|``tag`` | use case |
168+
+===============================+=======================================================================+
169+
|``internal: low bandwidth`` |allows users to filter out bandwidth-intensive examples like animations|
170+
+-------------------------------+-----------------------------------------------------------------------+
171+
|``internal: untagged`` |allows docs contributors to easily find untagged examples |
172+
+-------------------------------+-----------------------------------------------------------------------+
173+
|``internal: deprecated`` |examples containing deprecated functionality or concepts |
174+
+-------------------------------+-----------------------------------------------------------------------+
175+
|``internal: needs-review`` |example needs to be reviewed for accuracy or pedagogical value |
176+
+-------------------------------+-----------------------------------------------------------------------+
177+
|``internal: outstanding-todo`` |example has an unfinished to-do |
178+
+-------------------------------+-----------------------------------------------------------------------+
179+
|``internal: too-much`` |the example should be refined, split into multiple examples, or |
180+
| |reformatted into a tutorial or reference |
181+
+-------------------------------+-----------------------------------------------------------------------+

‎doc/devel/tag_guidelines.rst

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
Guidelines for assigning tags to gallery examples
2+
=================================================
3+
4+
Why do we need tags?
5+
--------------------
6+
7+
Tags serve multiple purposes.
8+
9+
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.
10+
11+
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.
12+
13+
Hidden tags provide additional functionality for maintainers and contributors.
14+
15+
What gets a tag?
16+
----------------
17+
18+
Every gallery example should be tagged with:
19+
20+
* 1+ content tags
21+
* structural, domain, or internal tag(s) if helpful
22+
23+
Tags can repeat existing forms of organization (e.g. an example is in the Animation folder and also gets an ``animation`` tag).
24+
25+
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.
26+
27+
**Tag Categories** - See :doc:`Tag Glossary <tag_glossary>` for a complete list of tags.
28+
29+
I. API tags: what content from the API reference is in the example?
30+
II. Structural tags: what format is the example? What context can we provide?
31+
III. Domain tags: what discipline(s) might seek this example consistently?
32+
IV. Internal tags: what information is helpful for maintainers or contributors?
33+
34+
Proposing new tags
35+
------------------
36+
37+
1. Review existing tag list, looking out for similar entries (i.e. ``axes`` and ``axis``).
38+
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.
39+
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.
40+
4. Tags can recreate other forms of organization.
41+
42+
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.
43+
44+
How to tag?
45+
-----------
46+
Put each tag as a directive at the bottom of the page.
47+
48+
Related content
49+
---------------
50+
51+
What is a gallery example?
52+
^^^^^^^^^^^^^^^^^^^^^^^^^^
53+
54+
The gallery of examples contains visual demonstrations of matplotlib features. Gallery examples exist so that users can scan through visual examples.
55+
56+
Unlike tutorials or user guides, gallery examples teach by demonstration, rather than by explanation or instruction.
57+
58+
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.
59+
60+
Format
61+
^^^^^^
62+
63+
All :ref:`examples-index` should aim to follow the following format:
64+
65+
* Title: 1-6 words, descriptive of content
66+
* Subtitle: 10-50 words, action-oriented description of the example subject
67+
* Image: a clear demonstration of the subject, showing edge cases and different applications if possible
68+
* Code + Text (optional): code, commented as appropriate + written text to add context if necessary
69+
70+
Example:
71+
72+
The ``bbox_intersect`` gallery example demonstrates the point of visual examples:
73+
74+
* 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
75+
* https://matplotlib.org/devdocs/gallery/misc/bbox_intersect.html#sphx-glr-gallery-misc-bbox-intersect-py

0 commit comments

Comments
 (0)