1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
Tag Glossary
============
.. contents::
:depth: 1
:local:
:backlinks: entry
API tags: what content from the API reference is in the example?
----------------------------------------------------------------
+-----------------------------------+---------------------------------------------+
|``tag`` | use case |
+===================================+=============================================+
|**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. 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?
---------------------------------------------------------------------------
These tags should be used only for development purposes; therefore please add them
separately behind a version guard:
.. code:: rst
.. ifconfig:: releaselevel == 'dev'
.. tags:: internal: needs-review
+-------------------------------+-----------------------------------------------------------------------+
|``tag`` | use case |
+===============================+=======================================================================+
|``internal: high-bandwidth`` |allows users to filter out bandwidth-intensive examples like animations|
+-------------------------------+-----------------------------------------------------------------------+
|``internal: untagged`` |allows docs contributors to easily find untagged examples |
+-------------------------------+-----------------------------------------------------------------------+
|``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 |
+-------------------------------+-----------------------------------------------------------------------+
|
