Matplotlib to chaco cheatsheet in docs

docs/source/user_manual/index.rst

@@ -26,3 +26,4 @@ User Guide
     common_patterns.rst
     how_do_i.rst
     faq.rst
+    matplotlib_to_chaco.rst

docs/source/user_manual/matplotlib_to_chaco.rst

@@ -0,0 +1,90 @@
+.. _matplotlib2chaco:
+
+##############################
+Matplotlib to Chaco Cheatsheet
+##############################
+As mentioned in the :ref:`Chaco Tutorial <tutorial>`,
+`matplotlib <https://matplotlib.org/>`_ and Chaco have different
+approaches to plotting (script-oriented vs. application-oriented). However, new
+users of Chaco who have worked with matplotlib in the past may find it useful
+to think about mapping "equivalent" code between the two.
+
+The following table lists various plotting related operations one might want to
+perform along with code for doing that using either Chaco or matplotlib. For
+the matplotlib code ``ax`` represents the Plot Axes
+i.e. ``fig, ax = plt.subplots()`` after importing
+``import matplotlib.pyplot as plt``. For more details see the
+`matplotlib User's Guide <https://matplotlib.org/stable/users/index.html>`_.
+For Chaco code, ``p`` is the :class:`~.Plot` instance.  ``x`` and ``y`` are the
+data to be plotted. In Chaco, this data needs to be wrapped in a
+``PlotData`` object. For example,
+
+::
+
+    import numpy as np
+    x = np.linspace(-2*np.pi, 2*np.pi, 100)
+    y = sin(x)
+
+    # Chaco only
+    pd = ArrayPlotData()
+    pd.set_data("x", x)
+    pd.set_data("y", y)
+    p = Plot(pd)
+
+Note that in the matplotlib column, ``x`` and ``y`` represent the data, but
+``'x'`` and ``'y'``, such as in the "X grid" and "Y Grid" rows are simply
+options for the ``axis`` argument. In Chaco ``'x'`` and ``'y'`` are the names
+the ``PlotData`` object associates with numpy arrays ``x`` and ``y``.
+
+.. list-table:: Matplotlib To Chaco Cheatsheet
+    :widths: 25 40 50
+    :header-rows: 1
+
+    * - What
+      - Matplotlib
+      - Chaco
+    * - Plot lines
+      - ``ax.plot(x, y)``
+      - ``p.plot(('x', 'y'))``
+    * - x label
+      - ``ax.set_xlabel('Time')``
+      - ``p.x_axis.title = 'Time'``
+    * - y label
+      - ``ax.set_ylabel('Value')``
+      - ``p.y_axis.title = 'Value'``
+    * - Title
+      - ``ax.set_title(title)``
+      - ``p.title = title``
+    * - X limits
+      - ``ax.set_xlim((low, high))``
+      - ``p.index_range.low_setting = low`` ``p.index_range.high_setting = high``
+    * - Y limits
+      - ``ax.set_ylim((low, high))``
+      - ``p.value_range.low_setting = low`` ``p.value_range.high_setting = high``
+    * - Label lines for legend
+      - ``ax.plot(…, label=label)``
+      - ``p.plot(…, name=name)``
+    * - Add legend
+      - ``ax.legend()``
+      - ``p.legend.visible = True``
+    * - Legend position
+      - ``ax.legend(loc='lower left')``
+      - ``p.legend_alignment = 'll'``
+    * - Background color
+      - ``ax.set_facecolor('white')``
+      - ``p.bgcolor = 'white'``
+    * - Show spines
+      - ``ax.spines.set_color('black')``
+      - ``p.border_visible = True``
+    * - Line width
+      - ``ax.plot(linewidth=lw)``
+      - ``p.line_width = 1.1`` or ``p.plot(…, linewidth=lw)``
+    * - X grid
+      - ``ax.grid(axis='x')``
+      - ``p.x_axis.visible = True``
+    * - Y grid
+      - ``ax.grid(axis='y')``
+      - ``p.y_axis.visible = True``
+    * - Second y ticks
+      - ``ax.yaxis.set_label_position('right')`` ``ax.yaxis.tick_right()``
+      - ``p.y_axis.orientation = "right"``