DOC: organize explain section

jklymak · jklymak · commit b1826280839a · 2023-01-14T16:37:37.000-08:00
diff --git a/doc/users/explain/index.rst b/doc/users/explain/index.rst
@@ -2,17 +2,52 @@
 
 .. redirect-from:: /users/explain
 
-Explanations
-------------
+################
+Using Matplotlib
+################
+
+Creating and interacting with visualizations
+############################################
+
+.. toctree::
+    :maxdepth: 1
+
+    ../../tutorials/introductory/quick_start.rst
+    ../../plot_types/index.rst
+    Arranging and laying out axes <layout/index.rst>
+    Customizing how Artists look <../../tutorials/introductory/customizing.rst>
+    Working with Artist objects <../../tutorials/intermediate/artists.rst>
+    Adding text to plots <text/index.rst>
+    Specifying and working with colors <../../tutorials/colors/index.rst>
+    Interacting with plots (zoom, pan, and more) <interactive.rst>
+    Animating plots <../../tutorials/introductory/animation_tutorial.rst>
+    Matplotlib toolkits (mplot3d, axes_grid1, axisartist) <../../tutorials/toolkits/index.rst>
+
+Important concepts
+##################
+
+.. toctree::
+    :maxdepth: 1
+
+    Pyplot versus Axes interfaces <api_interfaces.rst>
+    Backends: how plots get rendered to screen <backends.rst>
+    Using transforms <../../tutorials/advanced/transforms_tutorial.rst>
+    ../../tutorials/intermediate/autoscale.rst
+    ../../tutorials/intermediate/color_cycle.rst
+    ../../tutorials/intermediate/imshow_extent.rst
+    ../../gallery/images_contours_and_fields/image_antialiasing.rst
+
+
+Advanced topics
+###############
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
-    api_interfaces.rst
-    backends.rst
     writing_a_backend_pyplot_interface.rst
-    interactive.rst
-    fonts.rst
-    event_handling.rst
-    performance.rst
     interactive_guide.rst
+    performance.rst
+    ../../tutorials/advanced/blitting.rst
+    event_handling.rst
+    ../../tutorials/advanced/path_tutorial.rst
+    ../../tutorials/advanced/patheffects_guide.rst
diff --git a/doc/users/explain/layout/index.rst b/doc/users/explain/layout/index.rst
@@ -0,0 +1,31 @@
+
+########################################
+Arranging and laying out Axes (subplots)
+########################################
+
+.. plot::
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    fig, axs = plt.subplots(ncols=2, nrows=2, figsize=(3.5, 2.5),
+                            layout="constrained")
+    # add an artist, in this case a nice label in the middle...
+    for row in range(2):
+        for col in range(2):
+            axs[row, col].annotate(f'axs[{row}, {col}]', (0.5, 0.5),
+                                transform=axs[row, col].transAxes,
+                                ha='center', va='center', fontsize=18,
+                                color='darkgrey')
+    fig.suptitle('plt.subplots()')
+
+
+.. toctree::
+    :maxdepth: 1
+
+    ../../../tutorials/intermediate/arranging_axes.rst
+    ../../../gallery/subplots_axes_and_figures/colorbar_placement.rst
+    ../../../gallery/subplots_axes_and_figures/mosaic.rst
+    ../../../tutorials/intermediate/constrainedlayout_guide.rst
+    ../../../tutorials/intermediate/tight_layout_guide.rst
+
diff --git a/doc/users/explain/text/index.rst b/doc/users/explain/text/index.rst
@@ -0,0 +1,52 @@
+
+####################
+Adding text to plots
+####################
+
+.. plot::
+
+    import matplotlib
+    import matplotlib.pyplot as plt
+
+    fig = plt.figure()
+    ax = fig.add_subplot()
+    fig.subplots_adjust(top=0.85)
+
+    # Set titles for the figure and the subplot respectively
+    fig.suptitle('bold figure suptitle', fontsize=14, fontweight='bold')
+    ax.set_title('axes title')
+
+    ax.set_xlabel('xlabel')
+    ax.set_ylabel('ylabel')
+
+    # Set both x- and y-axis limits to [0, 10] instead of default [0, 1]
+    ax.axis([0, 10, 0, 10])
+
+    ax.text(3, 8, 'boxed italics text in data coords', style='italic',
+            bbox={'facecolor': 'red', 'alpha': 0.5, 'pad': 10})
+
+    ax.text(2, 6, r'an equation: $E=mc^2$', fontsize=15)
+
+    ax.text(3, 2, 'Unicode: Institut für Festkörperphysik')
+
+    ax.text(0.95, 0.01, 'colored text in axes coords',
+            verticalalignment='bottom', horizontalalignment='right',
+            transform=ax.transAxes,
+            color='green', fontsize=15)
+
+    ax.plot([2], [1], 'o')
+    ax.annotate('annotate', xy=(2, 1), xytext=(3, 4),
+                arrowprops=dict(facecolor='black', shrink=0.05))
+
+    plt.show()
+
+.. toctree::
+    :maxdepth: 1
+
+    ../../../tutorials/text/text_intro.rst
+    ../../../tutorials/intermediate/legend_guide.rst
+    ../../../tutorials/text/annotations.rst
+    ../../../tutorials/text/text_props.rst
+    ../../../tutorials/text/mathtext.rst
+    ../../../tutorials/text/usetex.rst
+    ../fonts.rst
diff --git a/doc/users/index.rst b/doc/users/index.rst
@@ -3,32 +3,22 @@
 .. redirect-from:: /contents
 
 
-###########
-Users guide
-###########
+######################
+Matplotlib Users guide
+######################
 
 General
 #######
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    getting_started/index.rst
    installing/index.rst
-   explain/index.rst
+   Using Matplotlib <explain/index.rst>
    faq/index.rst
    resources/index.rst
 
-Tutorials and examples
-######################
-
-.. toctree::
-   :maxdepth: 1
-
-   ../plot_types/index.rst
-   ../tutorials/index.rst
-   ../gallery/index.rst
-
 Reference
 #########
 
