Additional text and references for customization

jeromefv · jeromefv · commit bbebb168da50 · 2020-11-16T11:41:43.000-08:00
diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py
@@ -256,9 +256,9 @@
 # Implicit: ``pyplot``
 # --------------------
 #
-# To use implicit programming for Matplotlib involves using the ``pyplot``
+# Implicit programming for Matplotlib centers around using the ``pyplot``
 # module. The Figure and Axes are automatically generated by the module.
-# Pass data through as arguments using methods within the module.
+# The methods and functions within the module take incoming data as arguments.
 # Additional parts of the Figure are also available through the module
 # methods.
 
@@ -303,25 +303,28 @@
 # ==============
 #
 # There are two main parts to building a visualization with Matplotlib, the
-# `Figure`_ and the `Axes`_.
+# ``Figure`` and the ``Axes``.
 #
 # Components of Matplotlib Figure
 # -------------------------------
 #
-# The image below depicts each visible element of a Matplotlib graph.
-# **Note**: ``Figure`` and ``Axes`` identify empty regions of the diagram;
-# however, these elements are foundational in operation.
+# The image below depicts each visible element of a Matplotlib graph. The
+# graphic uses Matplotlib to display and highlight each individual part of the
+# visualization. The source code is available as :ref:`Anatomy-of-a-figure`.
+#
+# .. note::
+#
+#     ``Figure`` and ``Axes`` identify empty regions of the diagram;
+#     however, these elements are foundational in operation.
 #
 # .. image:: ../../_static/anatomy.png
 #
 # :class:`~matplotlib.figure.Figure`
-# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
 # The Figure is the working space for the programming. All visible
 # objects on a graph are located within the Figure.
 #
 # :class:`~matplotlib.axes.Axes`
-# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
 # Axes are subplots within the Figure. They contain Figure elements and
 # are responsible for plotting and configuring additional details. Each
@@ -331,7 +334,7 @@
 # Other Components
 # ^^^^^^^^^^^^^^^^
 #
-# * :class:`~matplotlib.artist.Artist`
+# :class:`~matplotlib.artist.Artist`
 #
 # Artists are the visible elements when the Figure is rendered. They
 # correspond to a specific Axes and cannot be shared or transferred.
@@ -352,7 +355,7 @@
 # Axes involved.
 #
 # When looking for more complex solutions to multiple graphs within a Figure,
-# use the GridSpec module to organize the layout.
+# use the :class:`matplotlib.gridspec.GridSpec` module to organize the layout.
 #
 # Explicit
 # ^^^^^^^^
@@ -363,7 +366,7 @@
                                sharey='row',
                                figsize=[8, 4],
                                constrained_layout=True)
-# Figure and two Axes unpacked from arguments (1, 2) as row & column
+# Figure and two Axes unpacked from arguments (1, 2) as row & column.
 # Keyword arguments provide additional details of sharing Y-axis, Figure size
 # and layout formatting.
 
@@ -462,6 +465,41 @@
 # Matplotlib auotmatically manages the specific Axes so that each action of
 # plotting data does not interfere with the previous instance.
 #
+# .. note::
+#
+#   There are limitations for customizing the implicit approach without
+#   referencing specific Axes and Artists within the Figure. For more
+#   advanced configurations, the explicit approach is recommended.
+#
+# Generalized Function Guidelines
+# -------------------------------
+#
+# For users with that have recurring plots and graphs, the Matplotlib
+# community recommends a signature function similar to the format below.
+
+
+def my_plotter(ax, data1, data2, param_dict):
+    """
+    Parameters
+    ----------
+    :param ax: Axes
+    :param data1: array of X data
+    :param data2: array of Y data
+    :param param_dict: Dictionary of keyword arguments to pass to method
+
+    Returns
+    -------
+    :returns: out : list of artists added
+    """
+    out = ax.plot(data1, data2, **param_dict)
+    # Note: Other methods from Axes class are also applicable.
+    return out
+
+##############################################################################
+#
+# .. currentmodule:: getting_started
+# .. autofunction:: my_plotter
+#
 # Additional Resources
 # ====================
 #
