<liclass="toctree-l1 has-children"><aclass="reference internal" href="development_setup.html">Setting up Matplotlib for development</a><details><summary><spanclass="toctree-toggle" role="presentation"><iclass="fa-solid fa-chevron-down"></i></span></summary><ul>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP12.html">MEP12: Improve Gallery and Examples</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP13.html">MEP13: Use properties for Artists</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP14.html">MEP14: Text handling</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP15.html">MEP15: Fix axis autoscaling when limits are specified for one axis only</a></li>
<h1>Guidelines for assigning tags to gallery examples<aclass="headerlink" href="#guidelines-for-assigning-tags-to-gallery-examples" title="Link to this heading">#</a></h1>
<sectionid="why-do-we-need-tags">
<h2>Why do we need tags?<aclass="headerlink" href="#why-do-we-need-tags" title="Link to this heading">#</a></h2>
<p>Tags serve multiple purposes.</p>
<p>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.</p>
<p>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.</p>
<p>Hidden tags provide additional functionality for maintainers and contributors.</p>
</section>
<sectionid="what-gets-a-tag">
<h2>What gets a tag?<aclass="headerlink" href="#what-gets-a-tag" title="Link to this heading">#</a></h2>
<p>Every gallery example should be tagged with:</p>
<ulclass="simple">
<li><p>1+ content tags</p></li>
<li><p>structural, domain, or internal tag(s) if helpful</p></li>
</ul>
<p>Tags can repeat existing forms of organization (e.g. an example is in the Animation folder and also gets an <codeclass="docutils literal notranslate"><spanclass="pre">animation</span></code> tag).</p>
<p>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 <codeclass="docutils literal notranslate"><spanclass="pre">legend</span></code> to indicate that, rather than changing the title or the scope of the example.</p>
<p><strong>Tag Categories</strong> - See <aclass="reference internal" href="tag_glossary.html"><spanclass="doc">Tag Glossary</span></a> for a complete list of tags.</p>
<olclass="upperroman simple">
<li><p>API tags: what content from the API reference is in the example?</p></li>
<li><p>Structural tags: what format is the example? What context can we provide?</p></li>
<li><p>Domain tags: what discipline(s) might seek this example consistently?</p></li>
<li><p>Internal tags: what information is helpful for maintainers or contributors?</p></li>
</ol>
</section>
<sectionid="proposing-new-tags">
<h2>Proposing new tags<aclass="headerlink" href="#proposing-new-tags" title="Link to this heading">#</a></h2>
<olclass="arabic simple">
<li><p>Review existing tag list, looking out for similar entries (i.e. <codeclass="docutils literal notranslate"><spanclass="pre">axes</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">axis</span></code>).</p></li>
<li><p>If a relevant tag or subcategory does not yet exist, propose it. Each tag is two parts: <codeclass="docutils literal notranslate"><spanclass="pre">subcategory:</span><spanclass="pre">tag</span></code>. Tags should be one or two words.</p></li>
<li><p>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.</p></li>
<li><p>Tags can recreate other forms of organization.</p></li>
</ol>
<p>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.</p>
</section>
<sectionid="how-to-tag">
<h2>How to tag?<aclass="headerlink" href="#how-to-tag" title="Link to this heading">#</a></h2>
<p>Put each tag as a directive at the bottom of the page.</p>
</section>
<sectionid="related-content">
<h2>Related content<aclass="headerlink" href="#related-content" title="Link to this heading">#</a></h2>
<sectionid="what-is-a-gallery-example">
<h3>What is a gallery example?<aclass="headerlink" href="#what-is-a-gallery-example" title="Link to this heading">#</a></h3>
<p>The gallery of examples contains visual demonstrations of matplotlib features. Gallery examples exist so that users can scan through visual examples.</p>
<p>Unlike tutorials or user guides, gallery examples teach by demonstration, rather than by explanation or instruction.</p>
<p>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.</p>
</section>
<sectionid="format">
<h3>Format<aclass="headerlink" href="#format" title="Link to this heading">#</a></h3>
<p>All <aclass="reference internal" href="../gallery/index.html#examples-index"><spanclass="std std-ref">Examples</span></a> should aim to follow the following format:</p>
<ulclass="simple">
<li><p>Title: 1-6 words, descriptive of content</p></li>
<li><p>Subtitle: 10-50 words, action-oriented description of the example subject</p></li>
<li><p>Image: a clear demonstration of the subject, showing edge cases and different applications if possible</p></li>
<li><p>Code + Text (optional): code, commented as appropriate + written text to add context if necessary</p></li>
</ul>
<p>Example:</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">bbox_intersect</span></code> gallery example demonstrates the point of visual examples:</p>
<ulclass="simple">
<li><p>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</p></li>