matplotlib · jklymak · Mar 17, 2023 · Feb 24, 2023 · Mar 4, 2023 · Mar 4, 2023
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -97,9 +97,12 @@ commands:
       - run:
           name: Install Python dependencies
           command: |
+            # remove when sphinx-gallery releases #1071:
             python -m pip install --user \
                 numpy<< parameters.numpy_version >> codecov coverage \
                 -r requirements/doc/doc-requirements.txt
+            python -m pip install --no-deps --user \
+                git+https://github.com/sphinx-gallery/sphinx-gallery.git
             python -m pip install --no-deps --user \
                 git+https://github.com/matplotlib/mpl-sphinx-theme.git
 

diff --git a/.flake8 b/.flake8
@@ -55,22 +55,22 @@ per-file-ignores =
     lib/pylab.py: F401, F403
 
     doc/conf.py: E402
-    galleries/tutorials/advanced/path_tutorial.py: E402
-    galleries/tutorials/advanced/patheffects_guide.py: E402
-    galleries/tutorials/advanced/transforms_tutorial.py: E402, E501
-    galleries/tutorials/colors/colormaps.py: E501
-    galleries/tutorials/colors/colors.py: E402
-    galleries/tutorials/intermediate/artists.py: E402
-    galleries/tutorials/intermediate/constrainedlayout_guide.py: E402
-    galleries/tutorials/intermediate/legend_guide.py: E402
-    galleries/tutorials/intermediate/tight_layout_guide.py: E402
-    galleries/tutorials/introductory/animation_tutorial.py: E501
-    galleries/tutorials/introductory/images.py: E501
-    galleries/tutorials/introductory/pyplot.py: E402, E501
-    galleries/tutorials/text/annotations.py: E402, E501
-    galleries/tutorials/text/mathtext.py: E501
-    galleries/tutorials/text/text_intro.py: E402
-    galleries/tutorials/text/text_props.py: E501
+    galleries/users_explain/artists/paths.py: E402
+    galleries/users_explain/artists/patheffects_guide.py: E402
+    galleries/users_explain/artists/transforms_tutorial.py: E402, E501
+    galleries/users_explain/colors/colormaps.py: E501
+    galleries/users_explain/colors/colors.py: E402
+    galleries/tutorials/artists.py: E402
+    galleries/users_explain/axes/constrainedlayout_guide.py: E402
+    galleries/users_explain/axes/legend_guide.py: E402
+    galleries/users_explain/axes/tight_layout_guide.py: E402
+    galleries/users_explain/animations/animations.py: E501
+    galleries/tutorials/images.py: E501
+    galleries/tutorials/pyplot.py: E402, E501
+    galleries/users_explain/text/annotations.py: E402, E501
+    galleries/users_explain/text/mathtext.py: E501
+    galleries/users_explain/text/text_intro.py: E402
+    galleries/users_explain/text/text_props.py: E501
 
     galleries/examples/animation/frame_grabbing_sgskip.py: E402
     galleries/examples/images_contours_and_fields/tricontour_demo.py: E201

diff --git a/doc/Makefile b/doc/Makefile
@@ -22,6 +22,7 @@ clean:
 	rm -rf "$(SOURCEDIR)/gallery"
 	rm -rf "$(SOURCEDIR)/plot_types"
 	rm -rf "$(SOURCEDIR)/tutorials"
+	rm -rf "$(SOURCEDIR)/users/explain"
 	rm -rf "$(SOURCEDIR)/savefig"
 	rm -rf "$(SOURCEDIR)/sphinxext/__pycache__"
 	rm -f $(SOURCEDIR)/_static/constrained_layout*.png

diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -75,7 +75,7 @@ programmatic plot generation.
 Further reading:
 
 - The `matplotlib.pyplot` function reference
-- :doc:`/tutorials/introductory/pyplot`
+- :ref:`pyplot_tutorial`
 - :ref:`Pyplot examples <pyplots_examples>`
 
 .. _api-index:

diff --git a/doc/api/prev_api_changes/api_changes_1.4.x.rst b/doc/api/prev_api_changes/api_changes_1.4.x.rst
@@ -88,7 +88,7 @@ original location:
 * The legend handler interface has changed from a callable, to any object
   which implements the ``legend_artists`` method (a deprecation phase will
   see this interface be maintained for v1.4). See
-  :doc:`/tutorials/intermediate/legend_guide` for further details. Further legend changes
+  :ref:`legend_guide` for further details. Further legend changes
   include:
 
    * ``matplotlib.axes.Axes._get_legend_handles`` now returns a generator of

diff --git a/doc/api/prev_api_changes/api_changes_2.2.0.rst b/doc/api/prev_api_changes/api_changes_2.2.0.rst
@@ -9,7 +9,7 @@ New dependency
 
 `kiwisolver <https://github.com/nucleic/kiwi>`__ is now a required
 dependency to support the new constrained_layout,  see
-:doc:`/tutorials/intermediate/constrainedlayout_guide` for
+:ref:`constrainedlayout_guide` for
 more details.
 
 

diff --git a/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst
@@ -24,7 +24,7 @@ library, so using it should be safe, but layouts may not be exactly the same as
 more development takes place.
 
 Details of using ``constrained_layout``, and its algorithm are available at
-:doc:`/tutorials/intermediate/constrainedlayout_guide`
+:ref:`constrainedlayout_guide`
 
 ``plt.subplot`` re-selection without keyword arguments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/doc/api/style_api.rst b/doc/api/style_api.rst
@@ -5,7 +5,7 @@
 Styles are predefined sets of `.rcParams` that define the visual appearance of
 a plot.
 
-:doc:`/tutorials/introductory/customizing` describes the mechanism and usage
+:ref:`customizing` describes the mechanism and usage
 of styles.
 
 The :doc:`/gallery/style_sheets/style_sheets_reference` gives an overview of

diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.rst
@@ -12,7 +12,7 @@ and feel as regular 2D plots.  Not the fastest or most feature complete 3D
 library out there, but it ships with Matplotlib and thus may be a lighter
 weight solution for some use cases.
 
-See the :doc:`mplot3d tutorial </tutorials/toolkits/mplot3d>` for
+See the :ref:`mplot3d tutorial <mplot3d>` for
 more information.
 
 .. image:: /_static/demo_mplot3d.png

diff --git a/doc/conf.py b/doc/conf.py
@@ -213,11 +213,14 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
         gallery_conf['image_srcset'] = []
     return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs)
 
-gallery_dirs = [f'{ed}' for ed in ['gallery', 'tutorials', 'plot_types']
+gallery_dirs = [f'{ed}' for ed in
+                ['gallery', 'tutorials', 'plot_types', 'users/explain']
                 if f'{ed}/*' not in skip_subdirs]
 
-example_dirs = [f'../galleries/{gd}'.replace('gallery', 'examples')
-                for gd in gallery_dirs]
+example_dirs = []
+for gd in gallery_dirs:
+    gd = gd.replace('gallery', 'examples').replace('users/explain', 'users_explain')
+    example_dirs += [f'../galleries/{gd}']
 
 sphinx_gallery_conf = {
     'backreferences_dir': Path('api') / Path('_as_gen'),
@@ -244,6 +247,7 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
     'thumbnail_size': (320, 224),
     'within_subsection_order': gallery_order.subsectionorder,
     'capture_repr': (),
+    'copyfile_regex': r'.*\.rst',
 }
 
 if 'plot_gallery=0' in sys.argv:

diff --git a/doc/devel/MEP/MEP29.rst b/doc/devel/MEP/MEP29.rst
@@ -54,7 +54,7 @@ Improvements
   to use the html.parser from the standard library.
 
 * Computation of text fragment positions could benefit from the OffsetFrom
-  class. See for example item 5 in `Using Complex Coordinates with Annotations <https://matplotlib.org/devdocs/tutorials/text/annotations.html#using-complex-coordinates-with-annotations>`_
+  class. See for example item 5 in `Using Complex Coordinates with Annotations <https://matplotlib.org/devdocs/users/explain/text/annotations.html#using-complex-coordinates-with-annotations>`_
 
 Problems
 --------

diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -202,15 +202,15 @@ Documents can be linked with the ``:doc:`` directive:
 
    See the :doc:`/users/installing/index`
 
-   See the tutorial :doc:`/tutorials/introductory/quick_start`
+   See the tutorial :ref:`quick_start`
 
    See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
 
 will render as:
 
   See the :doc:`/users/installing/index`
 
-  See the tutorial :doc:`/tutorials/introductory/quick_start`
+  See the tutorial :ref:`quick_start`
 
   See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
 
@@ -858,10 +858,9 @@ 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
-typically have more than one comment block (i.e.
-:doc:`/tutorials/introductory/quick_start`).  The first comment block
-can be the same as the example above.  Subsequent blocks of ReST text are
-delimited by the line ``# %%`` :
+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 ``# %%`` :
 
 .. code-block:: python
 

diff --git a/doc/index.rst b/doc/index.rst
@@ -49,9 +49,9 @@ Learning resources
         Tutorials
         ^^^
 
-        - :doc:`Quick-start guide <tutorials/introductory/quick_start>`
+        - :ref:`Quick-start guide <quick_start>`
         - :doc:`Plot types <plot_types/index>`
-        - :ref:`Introductory tutorials <tutorials-introductory>`
+        - :ref:`users-guide-using`
         - :doc:`External learning resources <users/resources/index>`
 
     .. grid-item-card::
@@ -69,11 +69,8 @@ Learning resources
         Understand how Matplotlib works
         ^^^
 
-        - The :ref:`users-guide-explain` in the :doc:`Users guide
-          <users/index>`
-        - Many of the :ref:`Intermediate <tutorials-intermediate>` and
-          :ref:`Advanced <tutorials-advanced>` tutorials have explanatory
-          material
+        - :ref:`users-guide-explain` in the :doc:`Users guide
+          <users/index>` has a number of advanced topics.
 
     .. grid-item-card::
         :padding: 2

diff --git a/doc/users/explain/index.rst b/doc/users/explain/index.rst
diff --git a/doc/users/faq/howto_faq.rst b/doc/users/faq/howto_faq.rst
@@ -97,7 +97,7 @@ actually perform such a rendering and inspect the result.
 Find all objects in a figure of a certain type
 ----------------------------------------------
 
-Every Matplotlib artist (see :doc:`/tutorials/intermediate/artists`) has a method
+Every Matplotlib artist (see :ref:`artists_tutorial`) has a method
 called :meth:`~matplotlib.artist.Artist.findobj` that can be used to
 recursively search the artist for any artists it may contain that meet
 some criteria (e.g., match all :class:`~matplotlib.lines.Line2D`
@@ -183,8 +183,8 @@ multiple ways to fix this:
   `.pyplot.subplots_adjust`.
 - Use one of the automatic layout mechanisms:
 
-  - constrained layout (:doc:`/tutorials/intermediate/constrainedlayout_guide`)
-  - tight layout (:doc:`/tutorials/intermediate/tight_layout_guide`)
+  - constrained layout (:ref:`constrainedlayout_guide`)
+  - tight layout (:ref:`tight_layout_guide`)
 
 - Calculate good values from the size of the plot elements yourself
   (:doc:`/gallery/subplots_axes_and_figures/auto_subplots_adjust`)

diff --git a/doc/users/faq/troubleshooting_faq.rst b/doc/users/faq/troubleshooting_faq.rst
@@ -106,7 +106,7 @@ provide the following information in your e-mail to the `mailing list
   GitHub, PyPI, or `Anaconda <https://www.anaconda.com/>`_).
 
 * Any customizations to your ``matplotlibrc`` file (see
-  :doc:`/tutorials/introductory/customizing`).
+  :ref:`customizing`).
 
 * If the problem is reproducible, please try to provide a *minimal*, standalone
   Python script that demonstrates the problem.  This is *the* critical step.

diff --git a/doc/users/getting_started/index.rst b/doc/users/getting_started/index.rst
@@ -51,5 +51,5 @@ Where to go next
 
 - Check out :doc:`Plot types </plot_types/index>` to get an overview of the
   types of plots you can create with Matplotlib.
-- Learn Matplotlib from the ground up in the
-  :doc:`Quick-start guide </tutorials/introductory/quick_start>`.
+- Learn Matplotlib from the ground up in the :ref:`Quick-start guide
+  <quick_start>`.
diff --git a/doc/users/installing/index.rst b/doc/users/installing/index.rst
@@ -219,7 +219,7 @@ example::
 
 This will give you additional information about which backends Matplotlib is
 loading, version information, and more. At this point you might want to make
-sure you understand Matplotlib's :doc:`configuration </tutorials/introductory/customizing>`
+sure you understand Matplotlib's :ref:`configuration <customizing>`
 process, governed by the :file:`matplotlibrc` configuration file which contains
 instructions within and the concept of the Matplotlib backend.
 

diff --git a/doc/users/prev_whats_new/dflt_style_changes.rst b/doc/users/prev_whats_new/dflt_style_changes.rst
@@ -98,7 +98,7 @@ are only specified via hex values.  To access these colors outside of
 the property cycling the notation for colors ``'CN'``, where ``N``
 takes values 0-9, was added to
 denote the first 10 colors in :rc:`axes.prop_cycle`. See
-:doc:`/tutorials/colors/colors` for more details.
+:ref:`colors_def` for more details.
 
 To restore the old color cycle use
 
@@ -147,7 +147,7 @@ watch Nathaniel Smith and Stéfan van der Walt's talk from SciPy2015.
 See `here for many more details <https://bids.github.io/colormap/>`__
 about the other alternatives and the tools used to create the color
 map.  For details on all of the colormaps available in matplotlib see
-:doc:`/tutorials/colors/colormaps`.
+:ref:`colormaps`.
 
 .. raw:: html
 

diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst
@@ -11,11 +11,11 @@ What's new in Matplotlib 0.99 (Aug 29, 2009)
 New documentation
 -----------------
 
-Jae-Joon Lee has written two new guides :doc:`/tutorials/intermediate/legend_guide`
+Jae-Joon Lee has written two new guides :ref:`legend_guide`
 and :ref:`plotting-guide-annotation`.  Michael Sarahan has written
-:doc:`/tutorials/introductory/images`.  John Hunter has written two new tutorials on
-working with paths and transformations: :doc:`/tutorials/advanced/path_tutorial` and
-:doc:`/tutorials/advanced/transforms_tutorial`.
+:ref:`image_tutorial`.  John Hunter has written two new tutorials on
+working with paths and transformations: :ref:`paths` and
+:ref:`transforms_tutorial`.
 
 .. _whats-new-mplot3d:
 
@@ -26,7 +26,7 @@ Reinier Heeres has ported John Porter's mplot3d over to the new
 matplotlib transformations framework, and it is now available as a
 toolkit mpl_toolkits.mplot3d (which now comes standard with all mpl
 installs).  See :ref:`mplot3d-examples-index` and
-:doc:`/tutorials/toolkits/mplot3d`.
+:ref:`mplot3d`.
 
 .. plot::
 

diff --git a/doc/users/prev_whats_new/whats_new_1.0.rst b/doc/users/prev_whats_new/whats_new_1.0.rst
@@ -23,7 +23,7 @@ Sophisticated subplot grid layout
 
 Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for
 doing complex subplot layouts, featuring row and column spans and
-more.  See :doc:`/tutorials/intermediate/arranging_axes` for a tutorial
+more.  See :ref:`arranging_axes` for a tutorial
 overview.
 
 .. figure:: ../../gallery/userdemo/images/sphx_glr_demo_gridspec01_001.png

diff --git a/doc/users/prev_whats_new/whats_new_1.1.rst b/doc/users/prev_whats_new/whats_new_1.1.rst
@@ -85,7 +85,7 @@ The usage of this functionality can be as simple as ::
 
 and it will adjust the spacing between subplots
 so that the axis labels do not overlap with neighboring subplots. A
-:doc:`/tutorials/intermediate/tight_layout_guide` has been created to show how to use
+:ref:`tight_layout_guide` has been created to show how to use
 this new tool.
 
 PyQT4, PySide, and IPython
@@ -114,7 +114,7 @@ legends for complex plots such as :meth:`~matplotlib.pyplot.stem` plots
 will now display correctly. Second, the 'best' placement of a legend has
 been improved in the presence of NANs.
 
-See the :doc:`/tutorials/intermediate/legend_guide` for more detailed explanation and
+See the :ref:`legend_guide` for more detailed explanation and
 examples.
 
 .. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_legend_demo_004.png
@@ -133,7 +133,7 @@ as 2D plotting, Ben Root has made several improvements to the
   improved to bring the class towards feature-parity with regular
   Axes objects
 
-* Documentation for :doc:`/tutorials/toolkits/mplot3d` was significantly expanded
+* Documentation for :ref:`mplot3d` was significantly expanded
 
 * Axis labels and orientation improved
 

diff --git a/doc/users/prev_whats_new/whats_new_1.2.rst b/doc/users/prev_whats_new/whats_new_1.2.rst
@@ -39,7 +39,7 @@ PGF/TikZ backend
 Peter Würtz wrote a backend that allows matplotlib to export figures as
 drawing commands for LaTeX. These can be processed by PdfLaTeX, XeLaTeX or
 LuaLaTeX using the PGF/TikZ package. Usage examples and documentation are
-found in :doc:`/tutorials/text/pgf`.
+found in :ref:`pgf`.
 
 .. image:: /_static/pgf_preamble.*
 

diff --git a/doc/users/prev_whats_new/whats_new_1.4.rst b/doc/users/prev_whats_new/whats_new_1.4.rst
@@ -406,7 +406,7 @@ instead of ``:context:`` any time you want to reset the context.
 
 Legend and PathEffects documentation
 ------------------------------------
-The :doc:`/tutorials/intermediate/legend_guide` and :doc:`/tutorials/advanced/patheffects_guide` have both been
+The :ref:`legend_guide` and :ref:`patheffects_guide` have both been
 updated to better reflect the full potential of each of these powerful
 features.
 

diff --git a/doc/users/prev_whats_new/whats_new_1.5.rst b/doc/users/prev_whats_new/whats_new_1.5.rst
@@ -104,8 +104,8 @@ defining property cycles. Adding cyclers together will be like you are
 You can even multiply cyclers, which is like using `itertools.product`
 on two or more property cycles.
 
-.. figure:: ../../tutorials/intermediate/images/sphx_glr_color_cycle_001.png
-   :target: ../../tutorials/intermediate/color_cycle.html
+.. figure:: /users/explain/artists/images/sphx_glr_color_cycle_001.png
+   :target: /users/explain/artists/color_cycle.html
    :align: center
    :scale: 50
 

diff --git a/doc/users/prev_whats_new/whats_new_2.2.rst b/doc/users/prev_whats_new/whats_new_2.2.rst
@@ -32,7 +32,7 @@ Features include:
   - Nested `~.GridSpec` layouts using `~.GridSpecFromSubplotSpec`.
 
   For more details and capabilities please see the new tutorial:
-  :doc:`/tutorials/intermediate/constrainedlayout_guide`
+  :ref:`constrainedlayout_guide`
 
 Note the new API to access this:
 

diff --git a/doc/users/prev_whats_new/whats_new_3.3.0.rst b/doc/users/prev_whats_new/whats_new_3.3.0.rst
@@ -50,7 +50,7 @@ or as a string (with single-character Axes labels):
                ha='center', va='center', fontsize=36,
                color='darkgrey')
 
-See :doc:`/gallery/subplots_axes_and_figures/mosaic` for more details and examples.
+See :ref:`mosaic` for more details and examples.
 
 ``GridSpec.subplots()``
 -----------------------