fixing tags

story645 · story645 · commit 214a6ecff4e3 · 2024-07-11T05:12:30.000-04:00
diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css
@@ -167,12 +167,13 @@ div.wide-table table th.stub {
     display: inline;
 }
 
-/*sdd is a custom class that strips out styling from dropdowns
-* Example usage:
-*
-* .. dropdown::
-     :class-container: sdd
-*/
+/* sdd is a custom class that strips out styling from dropdowns
+ * Example usage:
+ *
+ * .. dropdown::
+ *   :class-container: sdd
+ *
+ */
 
 .sdd.sd-dropdown {
     box-shadow: none!important;
@@ -196,9 +197,9 @@ div.wide-table table th.stub {
 /* section-toc is a custom class that removes the page title from a toctree listing
  * Example usage:
  *
- *     .. rst-class:: section-toc
+ * .. rst-class:: section-toc
+ * .. toctree::
  *
- *        .. toctree::
  */
 .section-toc.toctree-wrapper .toctree-l1>a{
     display: none;
diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -1059,45 +1059,52 @@ examples exist so that users can scan through visual examples. Unlike tutorials
 guides, gallery examples teach by demonstration, rather than by explanation or
 instruction.
 
-Gallery examples should contain a very brief description of *what* they demonstrate and,
-when relevant, *how* it is achieved. Avoid instructions or excessive explanation;
-instead, tag with related concepts and cross-link to relevant tutorials or user guides.
+Gallery examples should contain a very brief description of *what* is being demonstrated
+and, when relevant, *how* it is achieved. Explanations should be brief, providing only
+the minimal context necessary for understanding the example. Cross-link related
+documentation (e.g. tutorials, user guides and API entries) and tag the example with
+related concepts.
 
 Format
 ^^^^^^
 
 All :ref:`examples-index` should aim to follow these guidelines:
 
 :Title: Describe content in a short sentence (approx. 1-6 words). Do not use *demo* as
-        this is implied by being an example. Avoid implied verbs such as "creating,
-        making, etc", e.g. "annotated heatmaps" is preferred to "creating annotated
-        heatmaps". Use the simple present tense when a verb is necessary, e.g. *Fill the
+        this is implied by being an example. Avoid implied verbs such as *create*,
+        *make*, etc, e.g. *annotated heatmaps* is preferred to *create annotated
+        heatmaps*. Use the simple present tense when a verb is necessary, e.g. *Fill the
         area between two curves*
 
-:Subtitle: In a short paragraph (approx 1-3 sentences) describe what visualization
-           technique is being demonstrated and how library features are used to execute
-           the technique, e.g. *Set bar color and bar label entries using the color and
-           label parameters of ~Axes.bar*
+:Description: In a short paragraph (approx 1-3 sentences) describe what visualization
+              technique is being demonstrated and how library features are used to
+              execute the technique, e.g. *Set bar color and bar label entries using the
+              color and label parameters of ~Axes.bar*
 
 :Plot: Clearly demonstrate the subject and, when possible, show edge cases and different
        applications. While the plot should be visually appealing, prioritize keeping the
        plot uncluttered.
 
 :Code: Write the minimum necessary to showcase the feature that is the focus of the
-       example. Avoid styling and annotation-such as setting titles, legends, colors,
-       etc.- when it will not improve the clarity of the example.
+       example. Avoid custom styling and annotation (titles, legends, colors, etc.)
+       when it will not improve the clarity of the example.
 
-:Text: Use short comments sparingly to describe what hard to follow parts of code are
+       Use short comments sparingly to describe what hard to follow parts of code are
        doing. When more context or explanation is required, add a text paragraph before
        the code example.
 
-Example:
+:doc:`/gallery/misc/bbox_intersect` demonstrates the point of visual examples.
+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
 
-The ``bbox_intersect`` gallery example demonstrates the point of visual examples:
+:doc:`/gallery/images_contours_and_fields/colormap_interactive_adjustment` is an
+example of a good descriptive title that briefly summarizes how the showcased
+library features are used to implement the demonstrated visualization technique.
 
-* 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
+:doc:`/gallery/lines_bars_and_markers/lines_with_ticks_demo` is an example of having a
+minimal amount of code necessary to showcase the feature. The lack of extraneous code
+makes it easier for the reader to map which parts of code correspond to which parts of
+the plot.
 
 Miscellaneous
 =============
diff --git a/doc/devel/tag_guidelines.rst b/doc/devel/tag_guidelines.rst
@@ -18,16 +18,12 @@ Hidden tags provide additional functionality for maintainers and contributors.
 
 How to tag?
 -----------
-Place the tag directive at the bottom of each page and add the tags underneath
+Place the tag directive at the bottom of each page and add the tags underneath, e.g.:
 
-.. code-block:: python
-
-    # fig, ax = plt.subplots()
-    # ax.plot([1,2,3], [3,2,1], linestyle=':')
-    #
-    # .. tags::
-    #    plot-type: line, styling: texture,
+.. code-block:: rst
 
+    .. tags::
+       topic: tagging, purpose: reference
 
 What gets a tag?
 ----------------
diff --git a/pyproject.toml b/pyproject.toml
@@ -280,6 +280,8 @@ ignore_directives = [
     "ifconfig",
     # sphinx.ext.inheritance_diagram
     "inheritance-diagram",
+    # sphinx-tags
+    "tags",
     # include directive is causing attribute errors
     "include"
 ]

Original file line number	Diff line number	Diff line change
`@@ -280,6 +280,8 @@ ignore_directives = [`
`280`	`280`	`"ifconfig",`
`281`	`281`	`# sphinx.ext.inheritance_diagram`
`282`	`282`	`"inheritance-diagram",`
	`283`	`+ # sphinx-tags`
	`284`	`+ "tags",`
`283`	`285`	`# include directive is causing attribute errors`
`284`	`286`	`"include"`
`285`	`287`	`]`