From 1a3b32fa96806692404788df6baf914426ee1409 Mon Sep 17 00:00:00 2001 From: esibinga Date: Fri, 4 Aug 2023 09:45:15 -0400 Subject: [PATCH 01/15] tag guideline draft --- doc/devel/index.rst | 1 + galleries/examples/tag_glossary.rst | 155 ++++++++++++++++++++++++++ galleries/examples/tag_guidelines.rst | 70 ++++++++++++ 3 files changed, 226 insertions(+) create mode 100644 galleries/examples/tag_glossary.rst create mode 100644 galleries/examples/tag_guidelines.rst diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 2b358595255b..75088bce774a 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -146,6 +146,7 @@ Policies and guidelines document style_guide + ../gallery/tag_guidelines .. grid-item-card:: :shadow: none diff --git a/galleries/examples/tag_glossary.rst b/galleries/examples/tag_glossary.rst new file mode 100644 index 000000000000..439524f0b99c --- /dev/null +++ b/galleries/examples/tag_glossary.rst @@ -0,0 +1,155 @@ +: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? + + +*1. API tags: what content from the API reference is in the example?* + ++-----------------------------------+---------------------------------------------+ +|``tag`` | use case - if not obvious | ++===================================+=============================================+ +|**Styling** | ++-----------------------------------+---------------------------------------------+ +|``styling: color`` | | ++-----------------------------------+---------------------------------------------+ +|``styling: shape`` | | ++-----------------------------------+---------------------------------------------+ +|``styling: size`` | | ++-----------------------------------+---------------------------------------------+ +|``styling: position`` | | ++-----------------------------------+---------------------------------------------+ +|``styling: texture`` | | ++-----------------------------------+---------------------------------------------+ +|``styling: colormap`` | | ++-----------------------------------+---------------------------------------------+ +|``styling: colorbar`` | | ++-----------------------------------+---------------------------------------------+ +|``styling: linestyle`` | | ++-----------------------------------+---------------------------------------------+ +|``styling: small-multiples`` | | ++-----------------------------------+---------------------------------------------+ +| | | ++-----------------------------------+---------------------------------------------+ +|**Primary or relevant plot component** | ++-----------------------------------+---------------------------------------------+ +|Use these tags when plot contains a teachable example | ++-----------------------------------+---------------------------------------------+ +|``component: axes`` | | ++-----------------------------------+---------------------------------------------+ +|``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`` | | ++-----------------------------------+---------------------------------------------+ +| | | ++-----------------------------------+---------------------------------------------+ +|**Interactivity** | ++-----------------------------------+---------------------------------------------+ +|``interactivity: event handling`` | | ++-----------------------------------+---------------------------------------------+ +|``interactivity: zoom`` | | ++-----------------------------------+---------------------------------------------+ +|``interactivity: pan`` | | ++-----------------------------------+---------------------------------------------+ +|``interactivity: brush`` | | ++-----------------------------------+---------------------------------------------+ +| | | ++-----------------------------------+---------------------------------------------+ +|**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: `` | | ++-----------------------------------+---------------------------------------------+ + + +*2. Structural tags: what format is the example? What context can we provide?* + ++-----------------------+-------------------------------------------------------------------+ +|``tag`` | use case | ++=======================+===================================================================+ +|``level: reference`` |reference docs like "marker reference" or "list of named colors" | +| | - dense collection of short-format information | +| | - well-defined scope, accessible information | ++-----------------------+-------------------------------------------------------------------+ +|``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 | ++-----------------------+-------------------------------------------------------------------+ + +*3. Domain tags: what discipline(s) might seek this example consistently?* + +Note: 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`` | | ++-------------------------------+----------------------------------------+ +| | | ++-------------------------------+----------------------------------------+ + +*4. 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| ++---------------------------+-----------------------------------------------------------------------+ +|``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 | ++---------------------------+-----------------------------------------------------------------------+ diff --git a/galleries/examples/tag_guidelines.rst b/galleries/examples/tag_guidelines.rst new file mode 100644 index 000000000000..2fac2f8712c9 --- /dev/null +++ b/galleries/examples/tag_guidelines.rst @@ -0,0 +1,70 @@ +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 functions. 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 + +Examples with many tags may indicate that the entry is a showcase example. + +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 ` 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. + 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?* + where you put the directive is where the tag will show + +**Related content** + +*What is a gallery example?* + +The gallery of examples contains visual demonstrations of matplolib 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 gallery examples 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: + +``bbox_intersect`` gallery example showcases the point of visual examples + +* messy example/ hard to categorize, but the gallery is definitely the right spot for it because it's the kind of thing you'd find by visual search +* https://matplotlib.org/devdocs/gallery/misc/bbox_intersect.html#sphx-glr-gallery-misc-bbox-intersect-py From 86672afb63d0484e90ca6f6fb216662e8fd26d25 Mon Sep 17 00:00:00 2001 From: esibinga Date: Thu, 21 Sep 2023 00:14:07 -0400 Subject: [PATCH 02/15] carriage breaks --- galleries/examples/tag_guidelines.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/galleries/examples/tag_guidelines.rst b/galleries/examples/tag_guidelines.rst index 2fac2f8712c9..470b1b93e4c6 100644 --- a/galleries/examples/tag_guidelines.rst +++ b/galleries/examples/tag_guidelines.rst @@ -18,9 +18,9 @@ Every gallery example should be tagged with: * 1+ content tags * structural, domain, or internal tag(s) if helpful -Examples with many tags may indicate that the entry is a showcase example. + Examples with many tags may indicate that the entry is a showcase example. -Tags can repeat existing forms of organization (e.g. an example is in the Animation folder and also gets an ``animation`` tag). + 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. From af6366e1891d0ec427f3273e5cda3a92c0aec6fb Mon Sep 17 00:00:00 2001 From: esibinga Date: Thu, 21 Sep 2023 00:19:36 -0400 Subject: [PATCH 03/15] tabs --- galleries/examples/tag_guidelines.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/galleries/examples/tag_guidelines.rst b/galleries/examples/tag_guidelines.rst index 470b1b93e4c6..5d360240bbe2 100644 --- a/galleries/examples/tag_guidelines.rst +++ b/galleries/examples/tag_guidelines.rst @@ -38,7 +38,7 @@ IV. Internal tags: what information is helpful for maintainers or contributors? 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. + 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?* where you put the directive is where the tag will show From c87995e661c2d80e245806c2fd6ac4525c93c2c4 Mon Sep 17 00:00:00 2001 From: esibinga Date: Thu, 21 Sep 2023 00:23:27 -0400 Subject: [PATCH 04/15] indentation --- galleries/examples/tag_guidelines.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/galleries/examples/tag_guidelines.rst b/galleries/examples/tag_guidelines.rst index 5d360240bbe2..3354abfd963c 100644 --- a/galleries/examples/tag_guidelines.rst +++ b/galleries/examples/tag_guidelines.rst @@ -13,14 +13,14 @@ Guidelines for assigning tags to gallery examples *What gets a tag?* -Every gallery example should be tagged with: + Every gallery example should be tagged with: -* 1+ content tags -* structural, domain, or internal tag(s) if helpful + * 1+ content tags + * structural, domain, or internal tag(s) if helpful - Examples with many tags may indicate that the entry is a showcase example. + Examples with many tags may indicate that the entry is a showcase example. - Tags can repeat existing forms of organization (e.g. an example is in the Animation folder and also gets an ``animation`` tag). + 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. From c289586d91e92888d8686dae15dc6c77acd7a9cf Mon Sep 17 00:00:00 2001 From: esibinga Date: Thu, 5 Oct 2023 23:39:46 -0400 Subject: [PATCH 05/15] styling changes and Melissa's suggested changes --- galleries/examples/tag_guidelines.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/galleries/examples/tag_guidelines.rst b/galleries/examples/tag_guidelines.rst index 3354abfd963c..2fac2f8712c9 100644 --- a/galleries/examples/tag_guidelines.rst +++ b/galleries/examples/tag_guidelines.rst @@ -13,14 +13,14 @@ Guidelines for assigning tags to gallery examples *What gets a tag?* - Every gallery example should be tagged with: +Every gallery example should be tagged with: - * 1+ content tags - * structural, domain, or internal tag(s) if helpful +* 1+ content tags +* structural, domain, or internal tag(s) if helpful - Examples with many tags may indicate that the entry is a showcase example. +Examples with many tags may indicate that the entry is a showcase example. - Tags can repeat existing forms of organization (e.g. an example is in the Animation folder and also gets an ``animation`` tag). +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. @@ -38,7 +38,7 @@ IV. Internal tags: what information is helpful for maintainers or contributors? 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. +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?* where you put the directive is where the tag will show From ad4dee28baa63a34be5f97cce6015098f898c714 Mon Sep 17 00:00:00 2001 From: esibinga Date: Fri, 27 Oct 2023 14:24:49 -0400 Subject: [PATCH 06/15] changes to level and purpose --- galleries/examples/tag_glossary.rst | 80 +++++++++++++++++++---------- 1 file changed, 52 insertions(+), 28 deletions(-) diff --git a/galleries/examples/tag_glossary.rst b/galleries/examples/tag_glossary.rst index 439524f0b99c..5b4b79d07b5e 100644 --- a/galleries/examples/tag_glossary.rst +++ b/galleries/examples/tag_glossary.rst @@ -34,6 +34,9 @@ Tag Glossary +-----------------------------------+---------------------------------------------+ |``styling: small-multiples`` | | +-----------------------------------+---------------------------------------------+ +|``styling: conditional`` |styling is determined programmatically by a | +| |condition being met | ++-----------------------------------+---------------------------------------------+ | | | +-----------------------------------+---------------------------------------------+ |**Primary or relevant plot component** | @@ -66,18 +69,28 @@ Tag Glossary +-----------------------------------+---------------------------------------------+ |``component: error`` | | +-----------------------------------+---------------------------------------------+ +|``component: animation`` | | ++-----------------------------------+---------------------------------------------+ | | | +-----------------------------------+---------------------------------------------+ |**Interactivity** | +-----------------------------------+---------------------------------------------+ |``interactivity: event handling`` | | +-----------------------------------+---------------------------------------------+ +|``interactivity: click`` | | ++-----------------------------------+---------------------------------------------+ +|``interactivity: mouseover`` | | ++-----------------------------------+---------------------------------------------+ |``interactivity: zoom`` | | +-----------------------------------+---------------------------------------------+ |``interactivity: pan`` | | +-----------------------------------+---------------------------------------------+ |``interactivity: brush`` | | +-----------------------------------+---------------------------------------------+ +|``interactivity: drag`` | | ++-----------------------------------+---------------------------------------------+ +|``interactivity: scroll`` | | ++-----------------------------------+---------------------------------------------+ | | | +-----------------------------------+---------------------------------------------+ |**Plot Type** | @@ -96,27 +109,33 @@ Tag Glossary +-----------------------------------+---------------------------------------------+ |``plot type: specialty`` | | +-----------------------------------+---------------------------------------------+ -|``plot type: `` | | +|``plot type: scatter`` | | +-----------------------------------+---------------------------------------------+ *2. Structural tags: what format is the example? What context can we provide?* -+-----------------------+-------------------------------------------------------------------+ -|``tag`` | use case | -+=======================+===================================================================+ -|``level: reference`` |reference docs like "marker reference" or "list of named colors" | -| | - dense collection of short-format information | -| | - well-defined scope, accessible information | -+-----------------------+-------------------------------------------------------------------+ -|``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 | -+-----------------------+-------------------------------------------------------------------+ ++----------------------------+-------------------------------------------------------------------+ +|``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! | ++----------------------------+-------------------------------------------------------------------+ *3. Domain tags: what discipline(s) might seek this example consistently?* @@ -124,7 +143,7 @@ Note: it's futile to draw fences around "who owns what", and that's not the poin +-------------------------------+----------------------------------------+ |``tag`` | use case | -+=======================+================================================+ ++===============================+========================================+ |``domain`` |for whom is the example relevant? | +-------------------------------+----------------------------------------+ |``domain: cartography`` | | @@ -142,14 +161,19 @@ Note: it's futile to draw fences around "who owns what", and that's not the poin *4. 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| -+---------------------------+-----------------------------------------------------------------------+ -|``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 | -+---------------------------+-----------------------------------------------------------------------+ ++-------------------------------+-----------------------------------------------------------------------+ +|``tag`` | use case | ++===============================+=======================================================================+ +|``internal: low 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 | ++-------------------------------+-----------------------------------------------------------------------+ From 2ae0421894a9b4efada67120c275c2aa06954691 Mon Sep 17 00:00:00 2001 From: Eva Sibinga <46283995+esibinga@users.noreply.github.com> Date: Fri, 27 Oct 2023 15:03:27 -0400 Subject: [PATCH 07/15] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Melissa Weber Mendonça --- galleries/examples/tag_glossary.rst | 10 ++++------ galleries/examples/tag_guidelines.rst | 16 ++++++++-------- 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/galleries/examples/tag_glossary.rst b/galleries/examples/tag_glossary.rst index 5b4b79d07b5e..8aa7ebb18c60 100644 --- a/galleries/examples/tag_glossary.rst +++ b/galleries/examples/tag_glossary.rst @@ -3,10 +3,10 @@ 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? +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? *1. API tags: what content from the API reference is in the example?* @@ -156,8 +156,6 @@ Note: it's futile to draw fences around "who owns what", and that's not the poin +-------------------------------+----------------------------------------+ |``domain: signal-processing`` | | +-------------------------------+----------------------------------------+ -| | | -+-------------------------------+----------------------------------------+ *4. Internal tags: what information is helpful for maintainers or contributors?* diff --git a/galleries/examples/tag_guidelines.rst b/galleries/examples/tag_guidelines.rst index 2fac2f8712c9..1128699513eb 100644 --- a/galleries/examples/tag_guidelines.rst +++ b/galleries/examples/tag_guidelines.rst @@ -3,13 +3,13 @@ Guidelines for assigning tags to gallery examples *Why do we need tags?* - Tags serve multiple purposes. +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. +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 functions. They are helpful for users struggling to write a search query for what they're looking for. +They allow for better discoverability, search, and browse functions. 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. +Hidden tags provide additional functionality for maintainers and contributors. *What gets a tag?* @@ -33,10 +33,10 @@ 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. - 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. +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. +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. From b6d26414a75ba6ed912625c489cfd94f13cb22e3 Mon Sep 17 00:00:00 2001 From: Eva Sibinga <46283995+esibinga@users.noreply.github.com> Date: Sun, 29 Oct 2023 18:00:44 -0400 Subject: [PATCH 08/15] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Melissa Weber Mendonça --- galleries/examples/tag_glossary.rst | 12 ++++++++---- galleries/examples/tag_guidelines.rst | 23 +++++++++++++++-------- 2 files changed, 23 insertions(+), 12 deletions(-) diff --git a/galleries/examples/tag_glossary.rst b/galleries/examples/tag_glossary.rst index 8aa7ebb18c60..2bb2057d003f 100644 --- a/galleries/examples/tag_glossary.rst +++ b/galleries/examples/tag_glossary.rst @@ -9,7 +9,8 @@ III. Domain tags: what discipline(s) might seek this example consistently? IV. Internal tags: what information is helpful for maintainers or contributors? -*1. API tags: what content from the API reference is in the example?* +1. API tags: what content from the API reference is in the example? +------------------------------------------------------------------- +-----------------------------------+---------------------------------------------+ |``tag`` | use case - if not obvious | @@ -113,7 +114,8 @@ IV. Internal tags: what information is helpful for maintainers or contributors? +-----------------------------------+---------------------------------------------+ -*2. Structural tags: what format is the example? What context can we provide?* +2. Structural tags: what format is the example? What context can we provide? +---------------------------------------------------------------------------- +----------------------------+-------------------------------------------------------------------+ |``tag`` | use case | @@ -137,7 +139,8 @@ IV. Internal tags: what information is helpful for maintainers or contributors? |``purpose: fun`` |just for fun! | +----------------------------+-------------------------------------------------------------------+ -*3. Domain tags: what discipline(s) might seek this example consistently?* +3. Domain tags: what discipline(s) might seek this example consistently? +------------------------------------------------------------------------ Note: 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. @@ -157,7 +160,8 @@ Note: it's futile to draw fences around "who owns what", and that's not the poin |``domain: signal-processing`` | | +-------------------------------+----------------------------------------+ -*4. Internal tags: what information is helpful for maintainers or contributors?* +4. Internal tags: what information is helpful for maintainers or contributors? +------------------------------------------------------------------------------ +-------------------------------+-----------------------------------------------------------------------+ |``tag`` | use case | diff --git a/galleries/examples/tag_guidelines.rst b/galleries/examples/tag_guidelines.rst index 1128699513eb..d6061fc16647 100644 --- a/galleries/examples/tag_guidelines.rst +++ b/galleries/examples/tag_guidelines.rst @@ -1,7 +1,8 @@ Guidelines for assigning tags to gallery examples ================================================= -*Why do we need tags?* +Why do we need tags? +-------------------- Tags serve multiple purposes. @@ -11,7 +12,8 @@ They allow for better discoverability, search, and browse functions. They are he Hidden tags provide additional functionality for maintainers and contributors. -*What gets a tag?* +What gets a tag? +---------------- Every gallery example should be tagged with: @@ -24,14 +26,15 @@ Tags can repeat existing forms of organization (e.g. an example is in the Animat 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 ` for a complete list of tags. +**Tag Categories** - See :doc:`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* +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. @@ -40,12 +43,15 @@ IV. Internal tags: what information is helpful for maintainers or contributors? 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?* +How to tag? +----------- where you put the directive is where the tag will show -**Related content** +Related content +--------------- -*What is a gallery example?* +What is a gallery example? +^^^^^^^^^^^^^^^^^^^^^^^^^^ The gallery of examples contains visual demonstrations of matplolib features. Gallery examples exist so that users can scan through visual examples. @@ -53,7 +59,8 @@ Unlike tutorials or user guides, gallery examples teach by demonstration, rather 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: +Format +^^^^^^ All gallery examples should aim to follow the following format: From ed45c85bba7dd3d7e92ea366d67e0eb05667baa0 Mon Sep 17 00:00:00 2001 From: Eva Sibinga <46283995+esibinga@users.noreply.github.com> Date: Sun, 29 Oct 2023 19:04:07 -0400 Subject: [PATCH 09/15] Apply suggestions from code review Co-authored-by: hannah --- galleries/examples/tag_guidelines.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/galleries/examples/tag_guidelines.rst b/galleries/examples/tag_guidelines.rst index d6061fc16647..b0514e65e30d 100644 --- a/galleries/examples/tag_guidelines.rst +++ b/galleries/examples/tag_guidelines.rst @@ -8,7 +8,7 @@ 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 functions. They are helpful for users struggling to write a search query for what they're looking for. +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. From 71f25f49856b86700c423fae500f274998357837 Mon Sep 17 00:00:00 2001 From: esibinga Date: Sun, 29 Oct 2023 21:20:45 -0400 Subject: [PATCH 10/15] move docs back to devel, updates from review --- {galleries/examples => doc/devel}/tag_glossary.rst | 2 ++ {galleries/examples => doc/devel}/tag_guidelines.rst | 12 +++++------- 2 files changed, 7 insertions(+), 7 deletions(-) rename {galleries/examples => doc/devel}/tag_glossary.rst (98%) rename {galleries/examples => doc/devel}/tag_guidelines.rst (86%) diff --git a/galleries/examples/tag_glossary.rst b/doc/devel/tag_glossary.rst similarity index 98% rename from galleries/examples/tag_glossary.rst rename to doc/devel/tag_glossary.rst index 2bb2057d003f..e73a557a850a 100644 --- a/galleries/examples/tag_glossary.rst +++ b/doc/devel/tag_glossary.rst @@ -38,6 +38,8 @@ IV. Internal tags: what information is helpful for maintainers or contributors? |``styling: conditional`` |styling is determined programmatically by a | | |condition being met | +-----------------------------------+---------------------------------------------+ +|``styling: showcase`` |good showcase example | ++-----------------------------------+---------------------------------------------+ | | | +-----------------------------------+---------------------------------------------+ |**Primary or relevant plot component** | diff --git a/galleries/examples/tag_guidelines.rst b/doc/devel/tag_guidelines.rst similarity index 86% rename from galleries/examples/tag_guidelines.rst rename to doc/devel/tag_guidelines.rst index b0514e65e30d..ca6b8cfde01d 100644 --- a/galleries/examples/tag_guidelines.rst +++ b/doc/devel/tag_guidelines.rst @@ -20,8 +20,6 @@ Every gallery example should be tagged with: * 1+ content tags * structural, domain, or internal tag(s) if helpful -Examples with many tags may indicate that the entry is a showcase example. - 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. @@ -45,7 +43,7 @@ Note: Tagging organization aims to work for 80-90% of cases. Some examples fall How to tag? ----------- - where you put the directive is where the tag will show +Put each tag as a directive at the bottom of the page. Related content --------------- @@ -53,7 +51,7 @@ Related content What is a gallery example? ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The gallery of examples contains visual demonstrations of matplolib features. Gallery examples exist so that users can scan through visual examples. +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. @@ -62,7 +60,7 @@ Gallery examples should avoid instruction or excessive explanation except for br Format ^^^^^^ -All gallery examples should aim to follow the following 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 @@ -71,7 +69,7 @@ All gallery examples should aim to follow the following format: Example: -``bbox_intersect`` gallery example showcases the point of visual examples +The ``bbox_intersect`` gallery example demonstrates the point of visual examples: -* messy example/ hard to categorize, but the gallery is definitely the right spot for it because it's the kind of thing you'd find by visual search +* 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 From 00ba10d8f157e7ee7908e530dfa2500c8c30b58e Mon Sep 17 00:00:00 2001 From: Eva Sibinga <46283995+esibinga@users.noreply.github.com> Date: Mon, 30 Oct 2023 11:10:43 -0400 Subject: [PATCH 11/15] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Melissa Weber Mendonça --- doc/devel/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 75088bce774a..1d91aa2790b5 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -146,7 +146,7 @@ Policies and guidelines document style_guide - ../gallery/tag_guidelines + tag_guidelines .. grid-item-card:: :shadow: none From 87261c1934974e5e4527a8dbd0971aaa1fd48b97 Mon Sep 17 00:00:00 2001 From: esibinga Date: Mon, 30 Oct 2023 14:19:33 -0400 Subject: [PATCH 12/15] clarify component and styling --- doc/devel/tag_glossary.rst | 58 ++++++++++++++++++-------------------- 1 file changed, 28 insertions(+), 30 deletions(-) diff --git a/doc/devel/tag_glossary.rst b/doc/devel/tag_glossary.rst index e73a557a850a..8f775879aa75 100644 --- a/doc/devel/tag_glossary.rst +++ b/doc/devel/tag_glossary.rst @@ -15,38 +15,9 @@ IV. Internal tags: what information is helpful for maintainers or contributors? +-----------------------------------+---------------------------------------------+ |``tag`` | use case - if not obvious | +===================================+=============================================+ -|**Styling** | -+-----------------------------------+---------------------------------------------+ -|``styling: color`` | | -+-----------------------------------+---------------------------------------------+ -|``styling: shape`` | | -+-----------------------------------+---------------------------------------------+ -|``styling: size`` | | -+-----------------------------------+---------------------------------------------+ -|``styling: position`` | | -+-----------------------------------+---------------------------------------------+ -|``styling: texture`` | | -+-----------------------------------+---------------------------------------------+ -|``styling: colormap`` | | -+-----------------------------------+---------------------------------------------+ -|``styling: colorbar`` | | -+-----------------------------------+---------------------------------------------+ -|``styling: linestyle`` | | -+-----------------------------------+---------------------------------------------+ -|``styling: small-multiples`` | | -+-----------------------------------+---------------------------------------------+ -|``styling: conditional`` |styling is determined programmatically by a | -| |condition being met | -+-----------------------------------+---------------------------------------------+ -|``styling: showcase`` |good showcase example | -+-----------------------------------+---------------------------------------------+ -| | | -+-----------------------------------+---------------------------------------------+ |**Primary or relevant plot component** | +-----------------------------------+---------------------------------------------+ -|Use these tags when plot contains a teachable example | -+-----------------------------------+---------------------------------------------+ -|``component: axes`` | | +|``component: axes`` |remarkable or very clear use of component | +-----------------------------------+---------------------------------------------+ |``component: axis`` | | +-----------------------------------+---------------------------------------------+ @@ -76,6 +47,33 @@ IV. Internal tags: what information is helpful for maintainers or contributors? +-----------------------------------+---------------------------------------------+ | | | +-----------------------------------+---------------------------------------------+ +|**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 | ++-----------------------------------+---------------------------------------------+ +|``styling: showcase`` |good showcase example | ++-----------------------------------+---------------------------------------------+ +| | | ++-----------------------------------+---------------------------------------------+ |**Interactivity** | +-----------------------------------+---------------------------------------------+ |``interactivity: event handling`` | | From c45922bad4ecac90a302659c2fd15aa511ac5b47 Mon Sep 17 00:00:00 2001 From: esibinga Date: Mon, 30 Oct 2023 16:44:53 -0400 Subject: [PATCH 13/15] updates from review --- doc/devel/tag_glossary.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/devel/tag_glossary.rst b/doc/devel/tag_glossary.rst index 8f775879aa75..61765d5b7826 100644 --- a/doc/devel/tag_glossary.rst +++ b/doc/devel/tag_glossary.rst @@ -9,8 +9,8 @@ III. Domain tags: what discipline(s) might seek this example consistently? IV. Internal tags: what information is helpful for maintainers or contributors? -1. API tags: what content from the API reference is in the example? -------------------------------------------------------------------- +API tags: what content from the API reference is in the example? +---------------------------------------------------------------- +-----------------------------------+---------------------------------------------+ |``tag`` | use case - if not obvious | @@ -70,8 +70,6 @@ IV. Internal tags: what information is helpful for maintainers or contributors? |``styling: conditional`` |styling is determined programmatically by a | | |condition being met | +-----------------------------------+---------------------------------------------+ -|``styling: showcase`` |good showcase example | -+-----------------------------------+---------------------------------------------+ | | | +-----------------------------------+---------------------------------------------+ |**Interactivity** | @@ -114,8 +112,8 @@ IV. Internal tags: what information is helpful for maintainers or contributors? +-----------------------------------+---------------------------------------------+ -2. Structural tags: what format is the example? What context can we provide? ----------------------------------------------------------------------------- +Structural tags: what format is the example? What context can we provide? +------------------------------------------------------------------------- +----------------------------+-------------------------------------------------------------------+ |``tag`` | use case | @@ -138,11 +136,13 @@ IV. Internal tags: what information is helpful for maintainers or contributors? +----------------------------+-------------------------------------------------------------------+ |``purpose: fun`` |just for fun! | +----------------------------+-------------------------------------------------------------------+ +|``styling: showcase`` |good showcase example | ++----------------------------+-------------------------------------------------------------------+ -3. Domain tags: what discipline(s) might seek this example consistently? ------------------------------------------------------------------------- +Domain tags: what discipline(s) might seek this example consistently? +--------------------------------------------------------------------- -Note: 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. +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 | @@ -160,8 +160,8 @@ Note: it's futile to draw fences around "who owns what", and that's not the poin |``domain: signal-processing`` | | +-------------------------------+----------------------------------------+ -4. Internal tags: what information is helpful for maintainers or contributors? ------------------------------------------------------------------------------- +Internal tags: what information is helpful for maintainers or contributors? +--------------------------------------------------------------------------- +-------------------------------+-----------------------------------------------------------------------+ |``tag`` | use case | From afa15c4afe1b63736afe263fc750c73cdc042f76 Mon Sep 17 00:00:00 2001 From: Eva Sibinga <46283995+esibinga@users.noreply.github.com> Date: Mon, 30 Oct 2023 23:23:58 -0400 Subject: [PATCH 14/15] Apply suggestions from code review Co-authored-by: hannah --- doc/devel/tag_glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/tag_glossary.rst b/doc/devel/tag_glossary.rst index 61765d5b7826..9b70a2a96159 100644 --- a/doc/devel/tag_glossary.rst +++ b/doc/devel/tag_glossary.rst @@ -136,7 +136,7 @@ Structural tags: what format is the example? What context can we provide? +----------------------------+-------------------------------------------------------------------+ |``purpose: fun`` |just for fun! | +----------------------------+-------------------------------------------------------------------+ -|``styling: showcase`` |good showcase example | +|``purpose: showcase`` |good showcase example | +----------------------------+-------------------------------------------------------------------+ Domain tags: what discipline(s) might seek this example consistently? From 8326b514cd953c7b1c5e048303f921c32dea0584 Mon Sep 17 00:00:00 2001 From: esibinga Date: Tue, 31 Oct 2023 09:02:54 -0400 Subject: [PATCH 15/15] add template for new tag proposal issues --- .github/ISSUE_TEMPLATE/tag_proposal.yml | 26 +++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/tag_proposal.yml diff --git a/.github/ISSUE_TEMPLATE/tag_proposal.yml b/.github/ISSUE_TEMPLATE/tag_proposal.yml new file mode 100644 index 000000000000..1e3bceedf70c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/tag_proposal.yml @@ -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`