tried to address some of @jklymak's concerns

story645 · story645 · commit 7b68dbabcd9c · 2023-07-17T17:20:46.000-04:00
diff --git a/doc/index.rst b/doc/index.rst
@@ -11,151 +11,141 @@ Matplotlib |release| documentation
 Matplotlib is a comprehensive library for creating static, animated,
 and interactive visualizations in Python.
 
-.. raw:: html
+.. grid:: 1 1 2 2
 
-    <div class="grid__intro" id="image_rotator"></div>
+    .. grid-item::
 
+        .. raw:: html
 
-Matplotlib supports building fully custom visualizations and provides common
-visualization methods for the following use cases:
+            <div class="grid__intro" id="image_rotator"></div>
 
-.. toctree::
-    :maxdepth: 2
+    .. grid-item::
+
+        .. toctree::
+            :maxdepth: 2
+
+            plot_types/index.rst
 
-    plot_types/index.rst
 
 Install
 =======
 
-.. card::
+.. grid:: 1 1 2 2
 
-    .. tab-set::
+    .. grid-item-card:: Try this first!
 
-        .. tab-item:: Install using pip:
+        .. tab-set::
 
-            .. code-block:: bash
+            .. tab-item:: pip
 
-                pip install matplotlib
+                .. code-block:: bash
 
-        .. tab-item:: Install using conda:
+                    pip install matplotlib
 
-            .. code-block:: bash
+            .. tab-item:: conda
 
-                conda install -c conda-forge matplotlib
+                .. code-block:: bash
 
+                    conda install -c conda-forge matplotlib
 
-For more complex installations, see
+        Make first plot: :ref:`quick start <quick_start>`!
 
-.. toctree::
-    :maxdepth: 2
+    .. grid-item::
+
+        .. toctree::
+            :maxdepth: 2
 
-    users/installing/index.rst
+            users/installing/index.rst
 
+Learn
+=====
 
-Explanations and Reference
-==========================
+.. card:: How to use Matplotlib?
 
-.. plot::
+    .. grid:: 1 1 2 2
 
-    rng = np.random.default_rng(seed=19680808)
-    x = np.linspace(0, 4, 1000)  # Sample data.
-    y = rng.normal(size=len(x)) * 1.5 + x**2 + np.cumsum(rng.normal(size=len(x))) / 6
-    x = x[::10]
-    y = y[::10]
-    fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
+        .. grid-item::
 
-    ax.plot(x, x**2, label='underlying data', linewidth=4, alpha=0.6, color='k')
-    ax.scatter(x, y, s=13 * rng.random(size=len(x)), c=rng.normal(size=len(x)),
-        label='noisy data')
-    # p = np.polyfit(x, y, deg=1)
-    # print(p)
-    p = np.array([ 3.81283983, -2.00111268])
-    out = np.polyval(p, x)
-    ax.plot(x, out, label='linear fit')  # Plot some data on the axes.
-    # p = np.polyfit(x, y, deg=2)
-    # print(p)
-    p = np.array([ 1.18076933, -0.86768725,  1.05989268])
-    out = np.polyval(p, x)
-    ax.plot(x, out, label='quadratic fit')
-    ax.set_xlabel('x label')
-    ax.set_ylabel('y label')
-    ax.set_title("Simple plot")
-    ax.legend()
+            .. toctree::
+                :maxdepth: 1
 
+                users/explain/quick_start.rst
+                users/index.rst
+                tutorials/index.rst
+                users/faq/index.rst
 
-.. grid:: 1 1 2 2
 
-    .. grid-item-card:: User Guide and Tutorials
+        .. grid-item::
 
-        .. toctree::
-            :maxdepth: 1
+            .. toctree::
+                :maxdepth: 1
 
-            users/explain/quick_start.rst
-            users/explain/index.rst
-            tutorials/index.rst
-            users/faq/index.rst
+                gallery/index.rst
+                API reference <api/index>
+                Plotting reference <api/axes_api>
+                Figures reference <api/figure_api>
 
 
-    .. grid-item-card:: Examples and Reference
+Ecosystem
+=========
 
-        .. toctree::
-            :maxdepth: 1
+.. grid:: 1 1 2 2
+
+    .. grid-item-card::
 
-            gallery/index.rst
-            API reference <api/index>
-            Plotting reference <api/axes_api>
-            Figures reference <api/figure_api>
+        :octicon:`link-external;1em;sd-text-info` `Third-party packages <https://matplotlib.org/mpl-third-party/>`_
 
+        Custom, domain specific and experimental  features, such as
+        styling, alternative APIs, specialized plot types, backends and
+        helper methods.
 
-External resources
-==================
+    .. grid-item::
 
-Many packages extend the functionality of Matplotlib, for example by
-providing many styling options, alternative APIs, domain specific plot types,
-experimental features and backends, and helper methods. These are listed at:
+        .. toctree::
+            :maxdepth: 2
 
-`Third-party packages <https://matplotlib.org/mpl-third-party/>`_
+            users/resources/index.rst
 
-There are also a large number of books, videos, and tutorials teaching
-Matplotlib:
+        `Scientific Python <https://scientific-python.org/>`_
+
+
+About
+=====
 
 .. toctree::
     :maxdepth: 2
 
-    users/resources/index.rst
+    users/project/index.rst
 
 
 Contribute
 ==========
-Matplotlib is a community project maintained for and by its users. To learn more
-about contributing, please take a look at the contribution guide:
 
+.. grid:: 1 1 2 2
 
-.. toctree::
-    :maxdepth: 2
-
-    devel/index.rst
+    .. grid-item::
 
+        Matplotlib is a community project maintained for and by
+        its users and contributions of all kinds are very appreciated.
 
-Release Notes
-=============
+    .. grid-item::
+        .. toctree::
+            :maxdepth: 2
 
-Check the release notes for new features and API changes:
+            devel/index.rst
 
-.. toctree::
-    :maxdepth: 2
 
-    users/release_notes.rst
+Releases
+========
 
-About
-=====
-
-.. toctree::
-    :maxdepth: 2
+.. grid:: 1 1 2 2
 
-    users/project/index.rst
+    .. grid-item::
+        New versions are generally released every 6-8 months.
+        New features and API changes are described in the release notes.
 
-.. toctree::
-    :hidden:
+    .. grid-item::
+        .. toctree::
+            :maxdepth: 2
 
-    users/getting_started/index.rst
+            users/release_notes.rst
diff --git a/galleries/tutorials/index.rst b/galleries/tutorials/index.rst
@@ -115,7 +115,7 @@ a :ref:`FAQ <faq-index>` in our :ref:`user guide <users-guide-index>`.
 User guide tutorials
 --------------------
 
-Many of our tutorials were moved from this section to :ref:`users-guide-explain`:
+Many of our tutorials were moved from this section to :ref:`users-guide-index`:
 
 Introductory
 ~~~~~~~~~~~~
diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst
@@ -1,129 +1,5 @@
 .. _users-guide-explain:
-.. _users-guide-using:
-.. _users-guide-index:
 
-
-.. redirect-from:: /users/explain
-.. redirect-from:: /contents
-
-Using Matplotlib
-================
-
-
-.. grid:: 1 1 2 2
-
-   .. grid-item::
-
-      .. image:: ../../_static/anatomy.png
-
-
-   .. grid-item:: Parts of the figure
-
-      :class:`~matplotlib.artist.Artist`: Almost every visual element is managed
-      via a corresponding `~.Artist` object (or subclass) thatof that element.
-
-      :class:`~matplotlib.figure.Figure`:  A `~.Figure`` is roughly the total
-      drawing area and keeps track of the child :class:`~matplotlib.axes.Axes`,
-      figure related artists such as titles, figure legends, colorbars, and
-      nested subfigures.
-
-      :class:`~matplotlib.axes.Axes`: An `~.Axes` object manages a plotting
-      region. The `~.Axes` class contains most of the plotting methods, e.g.
-      ``ax.plot()``  is the `~.Axes.plot` method.
-
-
-      :class:`~matplotlib.axis.Axis`: The `.Axis` objects manage the
-      coordinate systems of the Axes by keeping track of the scales and limits
-      and storing the location and labeling of the tick marks on each Axis.
-
-.. grid:: 1 1 2 2
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :includehidden:
-
-            quick_start
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :includehidden:
-
-            figure/index
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :hidden:
-
-            axes/index
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :includehidden:
-
-            artists/index
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :includehidden:
-
-            customizing
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :includehidden:
-
-            axis/index
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :includehidden:
-
-            colors/index
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :includehidden:
-
-            text/index
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :includehidden:
-
-            animations/index
-
-    .. grid-item-card::
-        :padding: 2
-
-        .. toctree::
-            :maxdepth: 2
-            :includehidden:
-
-            toolkits/index
+====================
+User guide tutorials
+====================
