DOC: move tutorials [ci doc]

jklymak · jklymak · commit d5db532e9d09 · 2023-03-07T17:57:19.000-08:00
diff --git a/.flake8 b/.flake8
@@ -60,13 +60,13 @@ per-file-ignores =
     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/intermediate/artists.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/introductory/images.py: E501
-    galleries/tutorials/introductory/pyplot.py: E402, 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
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/index.rst b/doc/index.rst
@@ -51,7 +51,7 @@ Learning resources
 
         - :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/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`
diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst
@@ -13,7 +13,7 @@ New documentation
 
 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
+:ref:`image_tutorial`.  John Hunter has written two new tutorials on
 working with paths and transformations: :ref:`paths` and
 :ref:`transforms_tutorial`.
 
diff --git a/doc/users/project/history.rst b/doc/users/project/history.rst
@@ -68,10 +68,10 @@ The Matplotlib code is conceptually divided into three parts: the
 *pylab interface* is the set of functions provided by
 :mod:`pylab` which allow the user to create plots with code
 quite similar to MATLAB figure generating code
-(:doc:`/tutorials/introductory/pyplot`).  The *Matplotlib frontend* or *Matplotlib
+(:ref:`pyplot_tutorial`).  The *Matplotlib frontend* or *Matplotlib
 API* is the set of classes that do the heavy lifting, creating and
 managing figures, text, lines, plots and so on
-(:doc:`/tutorials/intermediate/artists`).  This is an abstract interface that knows
+(:ref:`artists_tutorial`).  This is an abstract interface that knows
 nothing about output.  The *backends* are device-dependent drawing
 devices, aka renderers, that transform the frontend representation to
 hardcopy or a display device (:ref:`what-is-a-backend`).  Example
diff --git a/galleries/tutorials/README.txt b/galleries/tutorials/README.txt
diff --git a/galleries/tutorials/advanced/README.txt b/galleries/tutorials/advanced/README.txt
diff --git a/galleries/tutorials/artists.py b/galleries/tutorials/artists.py
@@ -1,4 +1,8 @@
 """
+.. redirect-from:: /tutorials/intermediate/artists
+
+.. _artists_tutorial:
+
 ===============
 Artist tutorial
 ===============
@@ -716,6 +720,6 @@ class in the Matplotlib API, and the one you will be working with most
 # dollar signs and colors them green on the right side of the yaxis.
 #
 #
-# .. include:: ../../gallery/ticks/dollar_ticks.rst
+# .. include:: ../gallery/ticks/dollar_ticks.rst
 #    :start-after: .. redirect-from:: /gallery/pyplots/dollar_ticks
 #    :end-before: .. admonition:: References
diff --git a/galleries/tutorials/images.py b/galleries/tutorials/images.py
@@ -1,4 +1,8 @@
 """
+.. redirect-from:: /tutorials/introductory/images
+
+.. _image_tutorial:
+
 ==============
 Image tutorial
 ==============
@@ -65,7 +69,7 @@
 #
 # Here's the image we're going to play with:
 #
-# .. image:: ../../_static/stinkbug.png
+# .. image:: ../_static/stinkbug.png
 #
 # It's a 24-bit RGB PNG image (8 bits for each of R, G, B).  Depending
 # on where you get your data, the other kinds of image that you'll most
@@ -78,7 +82,7 @@
 # convert the `PIL.Image.Image` object into an 8-bit (``dtype=uint8``) numpy
 # array.
 
-img = np.asarray(Image.open('../../../doc/_static/stinkbug.png'))
+img = np.asarray(Image.open('../../doc/_static/stinkbug.png'))
 print(repr(img))
 
 # %%
@@ -227,7 +231,7 @@
 # We'll use the Pillow library that we used to load the image also to resize
 # the image.
 
-img = Image.open('../../../doc/_static/stinkbug.png')
+img = Image.open('../../doc/_static/stinkbug.png')
 img.thumbnail((64, 64))  # resizes image in-place
 imgplot = plt.imshow(img)
 
diff --git a/galleries/tutorials/index.rst b/galleries/tutorials/index.rst
@@ -0,0 +1,159 @@
+.. _tutorials:
+
+Tutorials
+=========
+
+This page contains a few tutorials for using Matplotlib.  For the old tutorials, see :ref:`below <user_guide_tutorials>`.
+
+For shorter examples, see our :ref:`examples page <examples-index>`.
+You can also find :ref:`external resources <resources-index>` and
+a :ref:`FAQ <faq-index>` in our :ref:`user guide <users-guide-index>`.
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbnails">
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="An introduction to the pyplot interface.  Please also see quick_start for an overview of how Ma...">
+
+.. only:: html
+
+  .. image:: /tutorials/images/thumb/sphx_glr_pyplot_thumb.png
+    :alt: Pyplot tutorial
+
+  :ref:`sphx_glr_tutorials_pyplot.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Pyplot tutorial</div>
+    </div>
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="A short tutorial on plotting images with Matplotlib.">
+
+.. only:: html
+
+  .. image:: /tutorials/images/thumb/sphx_glr_images_thumb.png
+    :alt: Image tutorial
+
+  :ref:`sphx_glr_tutorials_images.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Image tutorial</div>
+    </div>
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial aims to show the beginning, middle, and end of a single visualization using Matpl...">
+
+.. only:: html
+
+  .. image:: /tutorials/images/thumb/sphx_glr_lifecycle_thumb.png
+    :alt: The Lifecycle of a Plot
+
+  :ref:`sphx_glr_tutorials_lifecycle.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">The Lifecycle of a Plot</div>
+    </div>
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="Using Artist objects to render on the canvas.">
+
+.. only:: html
+
+  .. image:: /tutorials/images/thumb/sphx_glr_artists_thumb.png
+    :alt: Artist tutorial
+
+  :ref:`sphx_glr_tutorials_artists.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Artist tutorial</div>
+    </div>
+
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree::
+   :hidden:
+
+   /tutorials/pyplot
+   /tutorials/images
+   /tutorials/lifecycle
+   /tutorials/artists
+
+.. only:: html
+
+  .. container:: sphx-glr-footer sphx-glr-footer-gallery
+
+    .. container:: sphx-glr-download sphx-glr-download-python
+
+      :download:`Download all examples in Python source code: tutorials_python.zip </tutorials/tutorials_python.zip>`
+
+    .. container:: sphx-glr-download sphx-glr-download-jupyter
+
+      :download:`Download all examples in Jupyter notebooks: tutorials_jupyter.zip </tutorials/tutorials_jupyter.zip>`
+
+
+
+.. _user_guide_tutorials:
+
+User guide tutorials
+--------------------
+
+Many of our tutorials were moved from this section to :ref:`users-guide-explain`:
+
+Introductory
+~~~~~~~~~~~~
+
+- :ref:`quick_start`
+- :ref:`customizing`
+- :ref:`animations`
+
+Intermediate
+~~~~~~~~~~~~
+
+- :ref:`legend_guide`
+- :ref:`color_cycle`
+- :ref:`constrainedlayout_guide`
+- :ref:`tight_layout_guide`
+- :ref:`arranging_axes`
+- :ref:`autoscale`
+- :ref:`imshow_extent`
+
+Advanced
+~~~~~~~~
+
+- :ref:`blitting`
+- :ref:`paths`
+- :ref:`patheffects_guide`
+- :ref:`transforms_tutorial`
+
+Colors
+~~~~~~
+
+See :ref:`tutorials-colors`.
+
+Text
+~~~~
+
+See :ref:`tutorials-text`.
+
+Toolkits
+~~~~~~~~
+
+See :ref:`tutorials-toolkits`.
diff --git a/galleries/tutorials/intermediate/README.txt b/galleries/tutorials/intermediate/README.txt
diff --git a/galleries/tutorials/introductory/README.txt b/galleries/tutorials/introductory/README.txt
diff --git a/galleries/tutorials/lifecycle.py b/galleries/tutorials/lifecycle.py
@@ -1,4 +1,6 @@
 """
+.. redirect-from:: /tutorials/introductory/lifecycle
+
 =======================
 The Lifecycle of a Plot
 =======================
@@ -27,8 +29,8 @@
 :class:`axes.Axes` to build up the visualization in an instance of
 :class:`figure.Figure`.  In the implicit interface, inspired by and modeled on
 MATLAB, we use a global state-based interface which is encapsulated in the
-:mod:`.pyplot` module to plot to the "current Axes".  See the :doc:`pyplot
-tutorials </tutorials/introductory/pyplot>` for a more in-depth look at the
+:mod:`.pyplot` module to plot to the "current Axes".  See the :ref:`pyplot
+tutorials <pyplot_tutorial>` for a more in-depth look at the
 pyplot interface.
 
 Most of the terms are straightforward but the main thing to remember
diff --git a/galleries/tutorials/provisional/README.txt b/galleries/tutorials/provisional/README.txt
diff --git a/galleries/tutorials/pyplot.py b/galleries/tutorials/pyplot.py
@@ -1,4 +1,8 @@
 """
+.. redirect-from:: /tutorials/introductory/pyplot
+
+.. _pyplot_tutorial:
+
 ===============
 Pyplot tutorial
 ===============
@@ -307,7 +311,7 @@ def f(t):
 # it annoying that states (specifically the current image, figure and axes)
 # are being maintained for you behind the scenes, don't despair: this is just a thin
 # stateful wrapper around an object-oriented API, which you can use
-# instead (see :doc:`/tutorials/intermediate/artists`)
+# instead (see :ref:`artists_tutorial`)
 #
 # If you are making lots of figures, you need to be aware of one
 # more thing: the memory required for a figure is not completely
diff --git a/galleries/users_explain/figure/index.rst b/galleries/users_explain/figure/index.rst
@@ -111,7 +111,7 @@ Creating Figures
 ================
 
 By far the most common way to create a figure is using the
-:doc:`pyplot </tutorials/introductory/pyplot>` interface. As noted in
+:ref:`pyplot <pyplot_tutorial>` interface. As noted in
 :ref:`api_interfaces`, the pyplot interface serves two purposes.  One is to spin
 up the Backend and keep track of GUI windows. The other is a global state for
 Axes and Artists that allow a short-form API to plotting methods. In the
diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst
@@ -1,4 +1,5 @@
 .. _users-guide-explain:
+.. _users-guide-using:
 
 .. redirect-from:: /users/explain
 
diff --git a/pyproject.toml b/pyproject.toml
