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

.. admonition:: Template

   Template for further usage, template belong to matplotlib.

.. 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                               |
+-------------------------------+-----------------------------------------------------------------------+