Skip to content

Commit 48c8f07

Browse files
story645story645
authored
Merge pull request #28527 from story645/tag-guide
DOC: improve tagging guidelines page
2 parents 6b7b999 + 214a6ec commit 48c8f07

File tree

9 files changed

+143
-60
lines changed

9 files changed

+143
-60
lines changed

‎doc/Makefile

+1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ help:
1818
clean:
1919
@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
2020
rm -rf "$(SOURCEDIR)/build"
21+
rm -rf "$(SOURCEDIR)/_tags"
2122
rm -rf "$(SOURCEDIR)/api/_as_gen"
2223
rm -rf "$(SOURCEDIR)/gallery"
2324
rm -rf "$(SOURCEDIR)/plot_types"

‎doc/_static/mpl.css

+22
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,14 @@ div.wide-table table th.stub {
167167
display: inline;
168168
}
169169

170+
/* sdd is a custom class that strips out styling from dropdowns
171+
* Example usage:
172+
*
173+
* .. dropdown::
174+
* :class-container: sdd
175+
*
176+
*/
177+
170178
.sdd.sd-dropdown {
171179
box-shadow: none!important;
172180
}
@@ -185,3 +193,17 @@ div.wide-table table th.stub {
185193
.sdd.sd-dropdown .sd-card-header +.sd-card-body{
186194
--pst-sd-dropdown-color: none;
187195
}
196+
197+
/* section-toc is a custom class that removes the page title from a toctree listing
198+
* Example usage:
199+
*
200+
* .. rst-class:: section-toc
201+
* .. toctree::
202+
*
203+
*/
204+
.section-toc.toctree-wrapper .toctree-l1>a{
205+
display: none;
206+
}
207+
.section-toc.toctree-wrapper li>ul{
208+
padding-inline-start:0;
209+
}

‎doc/devel/document.rst

+56-3
Original file line numberDiff line numberDiff line change
@@ -894,8 +894,6 @@ these ``*.rst`` files from the source location to the build location (see
894894
In the Python files, to exclude an example from having a plot generated, insert
895895
"sgskip" somewhere in the filename.
896896

897-
Format examples
898-
---------------
899897

900898
The format of these files is relatively straightforward. Properly
901899
formatted comment blocks are treated as ReST_ text, the code is
@@ -937,7 +935,7 @@ like:
937935
The first comment block is treated as ReST_ text. The other comment blocks
938936
render as comments in :doc:`/gallery/lines_bars_and_markers/simple_plot`.
939937

940-
Tutorials are made with the exact same mechanism, except they are longer, and
938+
Tutorials are made with the exact same mechanism, except they are longer and
941939
typically have more than one comment block (i.e. :ref:`quick_start`). The
942940
first comment block can be the same as the example above. Subsequent blocks of
943941
ReST text are delimited by the line ``# %%`` :
@@ -1053,6 +1051,61 @@ subdirectory, but :file:`galleries/users_explain/artists` has a mix of
10531051
any ``*.rst`` files to a ``:toctree:``, either in the ``README.txt`` or in a
10541052
manual ``index.rst``.
10551053

1054+
Examples guidelines
1055+
-------------------
1056+
1057+
The gallery of examples contains visual demonstrations of matplotlib features. Gallery
1058+
examples exist so that users can scan through visual examples. Unlike tutorials or user
1059+
guides, gallery examples teach by demonstration, rather than by explanation or
1060+
instruction.
1061+
1062+
Gallery examples should contain a very brief description of *what* is being demonstrated
1063+
and, when relevant, *how* it is achieved. Explanations should be brief, providing only
1064+
the minimal context necessary for understanding the example. Cross-link related
1065+
documentation (e.g. tutorials, user guides and API entries) and tag the example with
1066+
related concepts.
1067+
1068+
Format
1069+
^^^^^^
1070+
1071+
All :ref:`examples-index` should aim to follow these guidelines:
1072+
1073+
:Title: Describe content in a short sentence (approx. 1-6 words). Do not use *demo* as
1074+
this is implied by being an example. Avoid implied verbs such as *create*,
1075+
*make*, etc, e.g. *annotated heatmaps* is preferred to *create annotated
1076+
heatmaps*. Use the simple present tense when a verb is necessary, e.g. *Fill the
1077+
area between two curves*
1078+
1079+
:Description: In a short paragraph (approx 1-3 sentences) describe what visualization
1080+
technique is being demonstrated and how library features are used to
1081+
execute the technique, e.g. *Set bar color and bar label entries using the
1082+
color and label parameters of ~Axes.bar*
1083+
1084+
:Plot: Clearly demonstrate the subject and, when possible, show edge cases and different
1085+
applications. While the plot should be visually appealing, prioritize keeping the
1086+
plot uncluttered.
1087+
1088+
:Code: Write the minimum necessary to showcase the feature that is the focus of the
1089+
example. Avoid custom styling and annotation (titles, legends, colors, etc.)
1090+
when it will not improve the clarity of the example.
1091+
1092+
Use short comments sparingly to describe what hard to follow parts of code are
1093+
doing. When more context or explanation is required, add a text paragraph before
1094+
the code example.
1095+
1096+
:doc:`/gallery/misc/bbox_intersect` demonstrates the point of visual examples.
1097+
This example is "messy" in that it's hard to categorize, but the gallery is the right
1098+
spot for it because it makes sense to find it by visual search
1099+
1100+
:doc:`/gallery/images_contours_and_fields/colormap_interactive_adjustment` is an
1101+
example of a good descriptive title that briefly summarizes how the showcased
1102+
library features are used to implement the demonstrated visualization technique.
1103+
1104+
:doc:`/gallery/lines_bars_and_markers/lines_with_ticks_demo` is an example of having a
1105+
minimal amount of code necessary to showcase the feature. The lack of extraneous code
1106+
makes it easier for the reader to map which parts of code correspond to which parts of
1107+
the plot.
1108+
10561109
Miscellaneous
10571110
=============
10581111

‎doc/devel/tag_glossary.rst

+16-8
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,17 @@
1-
:orphan:
2-
31
Tag Glossary
42
============
53

6-
I. API tags: what content from the API reference is in the example?
7-
II. Structural tags: what format is the example? What context can we provide?
8-
III. Domain tags: what discipline(s) might seek this example consistently?
9-
IV. Internal tags: what information is helpful for maintainers or contributors?
4+
.. contents::
5+
:depth: 1
6+
:local:
7+
:backlinks: entry
108

119

1210
API tags: what content from the API reference is in the example?
1311
----------------------------------------------------------------
1412

1513
+-----------------------------------+---------------------------------------------+
16-
|``tag`` | use case - if not obvious |
14+
|``tag`` | use case |
1715
+===================================+=============================================+
1816
|**Primary or relevant plot component** |
1917
+-----------------------------------+---------------------------------------------+
@@ -142,7 +140,9 @@ Structural tags: what format is the example? What context can we provide?
142140
Domain tags: what discipline(s) might seek this example consistently?
143141
---------------------------------------------------------------------
144142

145-
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.
143+
It's futile to draw fences around "who owns what", and that's not the point of domain
144+
tags. See below for a list of existing domain tags. If you don't see the one you're
145+
looking for and you think it should exist, consider proposing it.
146146

147147
+-------------------------------+----------------------------------------+
148148
|``tag`` | use case |
@@ -163,6 +163,14 @@ It's futile to draw fences around "who owns what", and that's not the point of d
163163
Internal tags: what information is helpful for maintainers or contributors?
164164
---------------------------------------------------------------------------
165165

166+
These tags should be used only for development purposes; therefore please add them
167+
separately behind a version guard:
168+
169+
.. code:: rst
170+
171+
.. ifconfig:: releaselevel == 'dev'
172+
.. tags:: internal: needs-review
173+
166174
+-------------------------------+-----------------------------------------------------------------------+
167175
|``tag`` | use case |
168176
+===============================+=======================================================================+

‎doc/devel/tag_guidelines.rst

+42-47
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,30 @@
1-
Guidelines for assigning tags to gallery examples
2-
=================================================
1+
Tagging guidelines
2+
==================
33

44
Why do we need tags?
55
--------------------
66

77
Tags serve multiple purposes.
88

9-
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.
9+
Tags have a one-to-many organization (i.e. one example can have several tags), while
10+
the gallery structure requires that examples are placed in only one location. This means
11+
tags provide a secondary layer of organization and make the gallery of examples more
12+
flexible and more user-friendly.
1013

11-
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.
14+
They allow for better discoverability, search, and browse functionality. They are
15+
helpful for users struggling to write a search query for what they're looking for.
1216

1317
Hidden tags provide additional functionality for maintainers and contributors.
1418

19+
How to tag?
20+
-----------
21+
Place the tag directive at the bottom of each page and add the tags underneath, e.g.:
22+
23+
.. code-block:: rst
24+
25+
.. tags::
26+
topic: tagging, purpose: reference
27+
1528
What gets a tag?
1629
----------------
1730

@@ -20,56 +33,38 @@ Every gallery example should be tagged with:
2033
* 1+ content tags
2134
* structural, domain, or internal tag(s) if helpful
2235

23-
Tags can repeat existing forms of organization (e.g. an example is in the Animation folder and also gets an ``animation`` tag).
36+
Tags can repeat existing forms of organization (e.g. an example is in the Animation
37+
folder and also gets an ``animation`` tag).
38+
39+
Tags are helpful to denote particularly good "byproduct" examples. E.g. the explicit
40+
purpose of a gallery example might be to demonstrate a colormap, but it's also a good
41+
demonstration of a legend. Tag ``legend`` to indicate that, rather than changing the
42+
title or the scope of the example.
2443

25-
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.
44+
.. card::
2645

27-
**Tag Categories** - See :doc:`Tag Glossary <tag_glossary>` for a complete list of tags.
46+
**Tag Categories**
47+
^^^
48+
.. rst-class:: section-toc
2849

29-
I. API tags: what content from the API reference is in the example?
30-
II. Structural tags: what format is the example? What context can we provide?
31-
III. Domain tags: what discipline(s) might seek this example consistently?
32-
IV. Internal tags: what information is helpful for maintainers or contributors?
50+
.. toctree::
51+
:maxdepth: 2
52+
53+
tag_glossary
54+
55+
+++
56+
See :doc:`Tag Glossary <tag_glossary>` for a complete list
3357

3458
Proposing new tags
3559
------------------
3660

3761
1. Review existing tag list, looking out for similar entries (i.e. ``axes`` and ``axis``).
38-
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.
39-
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.
62+
2. If a relevant tag or subcategory does not yet exist, propose it. Each tag is two
63+
parts: ``subcategory: tag``. Tags should be one or two words.
64+
3. New tags should be be added when they are relevant to existing gallery entries too.
65+
Avoid tags that will link to only a single gallery entry.
4066
4. Tags can recreate other forms of organization.
4167

42-
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.
43-
44-
How to tag?
45-
-----------
46-
Put each tag as a directive at the bottom of the page.
47-
48-
Related content
49-
---------------
50-
51-
What is a gallery example?
52-
^^^^^^^^^^^^^^^^^^^^^^^^^^
53-
54-
The gallery of examples contains visual demonstrations of matplotlib features. Gallery examples exist so that users can scan through visual examples.
55-
56-
Unlike tutorials or user guides, gallery examples teach by demonstration, rather than by explanation or instruction.
57-
58-
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.
59-
60-
Format
61-
^^^^^^
62-
63-
All :ref:`examples-index` should aim to follow the following format:
64-
65-
* Title: 1-6 words, descriptive of content
66-
* Subtitle: 10-50 words, action-oriented description of the example subject
67-
* Image: a clear demonstration of the subject, showing edge cases and different applications if possible
68-
* Code + Text (optional): code, commented as appropriate + written text to add context if necessary
69-
70-
Example:
71-
72-
The ``bbox_intersect`` gallery example demonstrates the point of visual examples:
73-
74-
* 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
75-
* https://matplotlib.org/devdocs/gallery/misc/bbox_intersect.html#sphx-glr-gallery-misc-bbox-intersect-py
68+
Tagging organization aims to work for 80-90% of cases. Some examples fall outside of the
69+
tagging structure. Niche or specific examples shouldn't be given standalone tags that
70+
won't apply to other examples.

‎doc/make.bat

+1
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ if "%1" == "show" goto show
3636
if "%1" == "clean" (
3737
REM workaround because sphinx does not completely clean up (#11139)
3838
rmdir /s /q "%SOURCEDIR%\build"
39+
rmdir /s /q "%SOURCEDIR%\_tags"
3940
rmdir /s /q "%SOURCEDIR%\api\_as_gen"
4041
rmdir /s /q "%SOURCEDIR%\gallery"
4142
rmdir /s /q "%SOURCEDIR%\plot_types"

‎environment.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ dependencies:
4040
- sphinx-copybutton
4141
- sphinx-gallery>=0.12.0
4242
- sphinx-design
43-
- sphinx-tags>=0.3.0
43+
- sphinx-tags>=0.4.0
4444
- pip
4545
- pip:
4646
- mpl-sphinx-theme~=3.8.0

‎pyproject.toml

+3
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,7 @@ ignore_directives = [
259259
# sphinxext.redirect_from
260260
"redirect-from",
261261
# sphinx-design
262+
"card",
262263
"dropdown",
263264
"grid",
264265
"tab-set",
@@ -279,6 +280,8 @@ ignore_directives = [
279280
"ifconfig",
280281
# sphinx.ext.inheritance_diagram
281282
"inheritance-diagram",
283+
# sphinx-tags
284+
"tags",
282285
# include directive is causing attribute errors
283286
"include"
284287
]

‎requirements/doc/doc-requirements.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,4 @@ sphinxcontrib-svg2pdfconverter>=1.1.0
2121
sphinx-copybutton
2222
sphinx-design
2323
sphinx-gallery>=0.12.0
24-
sphinx-tags>=0.3.0
24+
sphinx-tags>=0.4.0

0 commit comments

Comments
 (0)