From 33fa773805e9783bc3cead49b701a4660132446d Mon Sep 17 00:00:00 2001 From: hannah Date: Wed, 10 Jul 2024 03:52:50 -0400 Subject: [PATCH 1/3] added removed tags from make clean --- doc/Makefile | 1 + doc/make.bat | 1 + 2 files changed, 2 insertions(+) diff --git a/doc/Makefile b/doc/Makefile index 7eda39d87624..baed196a3ee2 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -18,6 +18,7 @@ help: clean: @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) rm -rf "$(SOURCEDIR)/build" + rm -rf "$(SOURCEDIR)/_tags" rm -rf "$(SOURCEDIR)/api/_as_gen" rm -rf "$(SOURCEDIR)/gallery" rm -rf "$(SOURCEDIR)/plot_types" diff --git a/doc/make.bat b/doc/make.bat index 37c74eb5079a..09d76404e60f 100644 --- a/doc/make.bat +++ b/doc/make.bat @@ -36,6 +36,7 @@ if "%1" == "show" goto show if "%1" == "clean" ( REM workaround because sphinx does not completely clean up (#11139) rmdir /s /q "%SOURCEDIR%\build" + rmdir /s /q "%SOURCEDIR%\_tags" rmdir /s /q "%SOURCEDIR%\api\_as_gen" rmdir /s /q "%SOURCEDIR%\gallery" rmdir /s /q "%SOURCEDIR%\plot_types" From 837650d182a98d3f5e214805413d47b76453a0c2 Mon Sep 17 00:00:00 2001 From: hannah Date: Mon, 8 Jul 2024 20:24:44 -0400 Subject: [PATCH 2/3] use glossery headings for category listings add coding example move content guidelines to writing guide enable multiline Co-authored-by: Eva Sibinga <46283995+esibinga@users.noreply.github.com> Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- doc/_static/mpl.css | 21 ++++++ doc/devel/document.rst | 52 ++++++++++++++- doc/devel/tag_glossary.rst | 24 ++++--- doc/devel/tag_guidelines.rst | 93 +++++++++++++-------------- environment.yml | 2 +- pyproject.toml | 1 + requirements/doc/doc-requirements.txt | 2 +- 7 files changed, 135 insertions(+), 60 deletions(-) diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index aae167d1f6f8..15be515ca8df 100644 --- a/doc/_static/mpl.css +++ b/doc/_static/mpl.css @@ -167,6 +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.sd-dropdown { box-shadow: none!important; } @@ -185,3 +192,17 @@ div.wide-table table th.stub { .sdd.sd-dropdown .sd-card-header +.sd-card-body{ --pst-sd-dropdown-color: none; } + +/* section-toc is a custom class that removes the page title from a toctree listing + * Example usage: + * + * .. rst-class:: section-toc + * + * .. toctree:: + */ +.section-toc.toctree-wrapper .toctree-l1>a{ + display: none; +} +.section-toc.toctree-wrapper li>ul{ + padding-inline-start:0; +} diff --git a/doc/devel/document.rst b/doc/devel/document.rst index 620c12c8db1c..0aae8ac878f2 100644 --- a/doc/devel/document.rst +++ b/doc/devel/document.rst @@ -894,8 +894,6 @@ these ``*.rst`` files from the source location to the build location (see In the Python files, to exclude an example from having a plot generated, insert "sgskip" somewhere in the filename. -Format examples ---------------- The format of these files is relatively straightforward. Properly formatted comment blocks are treated as ReST_ text, the code is @@ -937,7 +935,7 @@ like: The first comment block is treated as ReST_ text. The other comment blocks render as comments in :doc:`/gallery/lines_bars_and_markers/simple_plot`. -Tutorials are made with the exact same mechanism, except they are longer, and +Tutorials are made with the exact same mechanism, except they are longer and typically have more than one comment block (i.e. :ref:`quick_start`). The first comment block can be the same as the example above. Subsequent blocks of ReST text are delimited by the line ``# %%`` : @@ -1053,6 +1051,54 @@ subdirectory, but :file:`galleries/users_explain/artists` has a mix of any ``*.rst`` files to a ``:toctree:``, either in the ``README.txt`` or in a manual ``index.rst``. +Examples guidelines +------------------- + +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. + +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. + +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 + 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* + +: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. + +:Text: 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: + +The ``bbox_intersect`` gallery example 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 +* https://matplotlib.org/devdocs/gallery/misc/bbox_intersect.html#sphx-glr-gallery-misc-bbox-intersect-py + Miscellaneous ============= diff --git a/doc/devel/tag_glossary.rst b/doc/devel/tag_glossary.rst index 9a53de6358c8..b3d0ec2bcbda 100644 --- a/doc/devel/tag_glossary.rst +++ b/doc/devel/tag_glossary.rst @@ -1,19 +1,17 @@ -: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? +.. contents:: + :depth: 1 + :local: + :backlinks: entry API tags: what content from the API reference is in the example? ---------------------------------------------------------------- +-----------------------------------+---------------------------------------------+ -|``tag`` | use case - if not obvious | +|``tag`` | use case | +===================================+=============================================+ |**Primary or relevant plot component** | +-----------------------------------+---------------------------------------------+ @@ -142,7 +140,9 @@ Structural tags: what format is the example? What context can we provide? 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. 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. 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 | @@ -163,6 +163,14 @@ It's futile to draw fences around "who owns what", and that's not the point of d 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 | +===============================+=======================================================================+ diff --git a/doc/devel/tag_guidelines.rst b/doc/devel/tag_guidelines.rst index ca6b8cfde01d..faf5ccce3297 100644 --- a/doc/devel/tag_guidelines.rst +++ b/doc/devel/tag_guidelines.rst @@ -1,17 +1,34 @@ -Guidelines for assigning tags to gallery examples -================================================= +Tagging guidelines +================== 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. +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 functionality. 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. +How to tag? +----------- +Place the tag directive at the bottom of each page and add the tags underneath + +.. code-block:: python + + # fig, ax = plt.subplots() + # ax.plot([1,2,3], [3,2,1], linestyle=':') + # + # .. tags:: + # plot-type: line, styling: texture, + + What gets a tag? ---------------- @@ -20,56 +37,38 @@ Every gallery example should be tagged with: * 1+ content tags * structural, domain, or internal tag(s) if helpful -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. +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. +.. card:: -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? + **Tag Categories** + ^^^ + .. rst-class:: section-toc + + .. toctree:: + :maxdepth: 2 + + tag_glossary + + +++ + See :doc:`Tag Glossary ` for a complete list 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. +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? ------------ -Put each tag as a directive at the bottom of the page. - -Related content ---------------- - -What is a gallery example? -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -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. - -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 :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 -* 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: - -The ``bbox_intersect`` gallery example 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 -* https://matplotlib.org/devdocs/gallery/misc/bbox_intersect.html#sphx-glr-gallery-misc-bbox-intersect-py +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. diff --git a/environment.yml b/environment.yml index 2930ccf17e83..ccd5270e9149 100644 --- a/environment.yml +++ b/environment.yml @@ -40,7 +40,7 @@ dependencies: - sphinx-copybutton - sphinx-gallery>=0.12.0 - sphinx-design - - sphinx-tags>=0.3.0 + - sphinx-tags>=0.4.0 - pip - pip: - mpl-sphinx-theme~=3.8.0 diff --git a/pyproject.toml b/pyproject.toml index 52bbe308c0f9..1a2a1e77521a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -259,6 +259,7 @@ ignore_directives = [ # sphinxext.redirect_from "redirect-from", # sphinx-design + "card", "dropdown", "grid", "tab-set", diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index 87bc483b15c0..cee389da9e94 100644 --- a/requirements/doc/doc-requirements.txt +++ b/requirements/doc/doc-requirements.txt @@ -21,4 +21,4 @@ sphinxcontrib-svg2pdfconverter>=1.1.0 sphinx-copybutton sphinx-design sphinx-gallery>=0.12.0 -sphinx-tags>=0.3.0 +sphinx-tags>=0.4.0 From 214a6ecff4e33c0d11d6f1d8546f4f388191302c Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 11 Jul 2024 05:11:44 -0400 Subject: [PATCH 3/3] fixing tags --- doc/_static/mpl.css | 17 +++++++------- doc/devel/document.rst | 43 +++++++++++++++++++++--------------- doc/devel/tag_guidelines.rst | 12 ++++------ pyproject.toml | 2 ++ 4 files changed, 40 insertions(+), 34 deletions(-) diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index 15be515ca8df..9049ddbd8334 100644 --- 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 index 0aae8ac878f2..81b44a830c34 100644 --- a/doc/devel/document.rst +++ b/doc/devel/document.rst @@ -1059,9 +1059,11 @@ 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 ^^^^^^ @@ -1069,35 +1071,40 @@ 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 index faf5ccce3297..2c80065982bc 100644 --- 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 index 1a2a1e77521a..14ad28d23603 100644 --- 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" ]