From 0e26ab813853aed326995bf6a8d40091eca96fa7 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Wed, 17 Mar 2021 14:59:00 -0700 Subject: [PATCH 1/9] DOC: simplify API index --- doc/api/index.rst | 125 +++++++++++++++++++++++++++------------------- 1 file changed, 73 insertions(+), 52 deletions(-) diff --git a/doc/api/index.rst b/doc/api/index.rst index c247a169e304..da7c6a95225f 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -1,67 +1,39 @@ -API Overview -============ +API +=== -.. toctree:: - :hidden: +For recent changes, see :doc:`api_changes`. - api_changes +Much of the library can be accessed by creating :doc:`Figure ` +and :doc:`Axes ` objects and accessing methods on them. -.. contents:: :local: + - :doc:`figure_api`: axes creation, figure-level artists + - :doc:`axes_api`: most plotting methods, axes labels, access to + axis styling, etc. -See also the :doc:`api_changes`. +Simple example: note how the ``ax`` object has the `.axes.Axes.plot` method +that is used to create the line plot. + +.. plot:: + :include-source: + :align: center -Usage patterns --------------- + import matplotlib.pyplot as plt + import numpy as np -Below we describe several common approaches to plotting with Matplotlib. + x = np.arange(0, 4, 0.1) + y = np.sin(x*np.pi) -The pyplot API -^^^^^^^^^^^^^^ + fig, ax = plt.subplots(figsize=(3,2), constrained_layout=True) + ax.plot(x, y) + ax.set_xlabel('t [s]') + ax.set_ylabel('S [V]') + fig.suptitle('Sine wave') -`matplotlib.pyplot` is a collection of command style functions that make -Matplotlib work like MATLAB. Each pyplot function makes some change to a -figure: e.g., creates a figure, creates a plotting area in a figure, plots -some lines in a plotting area, decorates the plot with labels, etc. - -`.pyplot` is mainly intended for interactive plots and simple cases of -programmatic plot generation. - -Further reading: - -- The `matplotlib.pyplot` function reference -- :doc:`/tutorials/introductory/pyplot` -- :ref:`Pyplot examples ` - -.. _api-index: - -The object-oriented API -^^^^^^^^^^^^^^^^^^^^^^^ - -At its core, Matplotlib is object-oriented. We recommend directly working -with the objects, if you need more control and customization of your plots. - -In many cases you will create a `.Figure` and one or more -`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work -on these objects. However, it's also possible to create `.Figure`\ s -explicitly (e.g. when including them in GUI applications). - -Further reading: - -- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of - plotting functions. -- Most of the :ref:`examples ` use the object-oriented approach - (except for the pyplot section) - -The pylab API (disapproved) -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: pylab - :no-members: Modules ------- -Matplotlib consists of the following submodules: +Alphabetical list of all submodules: .. toctree:: :maxdepth: 1 @@ -147,3 +119,52 @@ Matplotlib. The following toolkits are included: toolkits/axes_grid1.rst toolkits/axisartist.rst toolkits/axes_grid.rst + + +Usage patterns +-------------- + +Below we describe several common approaches to plotting with Matplotlib. + +The pyplot API +^^^^^^^^^^^^^^ + +`matplotlib.pyplot` is a collection of command style functions that make +Matplotlib work like MATLAB. Each pyplot function makes some change to a +figure: e.g., creates a figure, creates a plotting area in a figure, plots +some lines in a plotting area, decorates the plot with labels, etc. + +`.pyplot` is mainly intended for interactive plots and simple cases of +programmatic plot generation. + +Further reading: + +- The `matplotlib.pyplot` function reference +- :doc:`/tutorials/introductory/pyplot` +- :ref:`Pyplot examples ` + +.. _api-index: + +The object-oriented API +^^^^^^^^^^^^^^^^^^^^^^^ + +At its core, Matplotlib is object-oriented. We recommend directly working +with the objects, if you need more control and customization of your plots. + +In many cases you will create a `.Figure` and one or more +`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work +on these objects. However, it's also possible to create `.Figure`\ s +explicitly (e.g. when including them in GUI applications). + +Further reading: + +- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of + plotting functions. +- Most of the :ref:`examples ` use the object-oriented approach + (except for the pyplot section) + +The pylab API (disapproved) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pylab + :no-members: From 94ced2626a47c5119db7c8d01d49945db2fb0d3b Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Wed, 17 Mar 2021 18:55:03 -0700 Subject: [PATCH 2/9] FIX --- doc/api/index.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/api/index.rst b/doc/api/index.rst index da7c6a95225f..1472602c00a7 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -1,6 +1,11 @@ API === +.. toctree:: + :hidden: + + api_changes + For recent changes, see :doc:`api_changes`. Much of the library can be accessed by creating :doc:`Figure ` From e80f6b800a622f3de574be75a5fb2a161a8e7330 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Wed, 17 Mar 2021 22:05:38 -0700 Subject: [PATCH 3/9] More edits --- doc/api/index.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/api/index.rst b/doc/api/index.rst index 1472602c00a7..3fc492d4d79f 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -8,15 +8,20 @@ API For recent changes, see :doc:`api_changes`. -Much of the library can be accessed by creating :doc:`Figure ` -and :doc:`Axes ` objects and accessing methods on them. +Much of the library is accessed by creating :doc:`Figure ` +and :doc:`Axes ` objects and calling methods on them. - :doc:`figure_api`: axes creation, figure-level artists - :doc:`axes_api`: most plotting methods, axes labels, access to axis styling, etc. -Simple example: note how the ``ax`` object has the `.axes.Axes.plot` method -that is used to create the line plot. + +(Note that there is also a parallel `matplotlib.pyplot` API interface +that is considered useful for interactive work; see +:ref:`usage patterns `, below). + +Simple example: the ``ax`` object has an `.axes.Axes.plot` method +that is used to create the line plot. .. plot:: :include-source: @@ -125,7 +130,9 @@ Matplotlib. The following toolkits are included: toolkits/axisartist.rst toolkits/axes_grid.rst - + +.. _usage_patterns: + Usage patterns -------------- From 3c9d40bc6764c6eb3372548b06a00e29b008e188 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Thu, 18 Mar 2021 06:32:21 -0700 Subject: [PATCH 4/9] FIX: add API to top banner --- doc/_templates/layout.html | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index e7a540e74967..0b6f475d203d 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -56,6 +56,7 @@
  • Installation
  • Documentation
    • +
  • API
  • Examples
  • Tutorials
  • Contributing
    • From 80293826cfaf5fe6fc14ef85c785b89755f07685 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Thu, 18 Mar 2021 13:22:21 -0700 Subject: [PATCH 5/9] Apply suggestions from code review Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- doc/api/index.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/api/index.rst b/doc/api/index.rst index 3fc492d4d79f..f1c008ac5c19 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -8,11 +8,12 @@ API For recent changes, see :doc:`api_changes`. -Much of the library is accessed by creating :doc:`Figure ` -and :doc:`Axes ` objects and calling methods on them. +When using the library you will typically create +:doc:`Figure ` and :doc:`Axes ` objects and +call their methods to add content and modify the apprearance. - - :doc:`figure_api`: axes creation, figure-level artists - - :doc:`axes_api`: most plotting methods, axes labels, access to + - :doc:`figure_api`: axes creation, figure-level content + - :doc:`axes_api`: most plotting methods, Axes labels, access to axis styling, etc. @@ -20,8 +21,8 @@ and :doc:`Axes ` objects and calling methods on them. that is considered useful for interactive work; see :ref:`usage patterns `, below). -Simple example: the ``ax`` object has an `.axes.Axes.plot` method -that is used to create the line plot. +Example: We create a Figure ``fig`` and Axes ``ax``. Then we call +methods on them to plot data, add axis labels and a figure title. .. plot:: :include-source: @@ -43,7 +44,7 @@ that is used to create the line plot. Modules ------- -Alphabetical list of all submodules: +Alphabetical list of submodules: .. toctree:: :maxdepth: 1 @@ -141,7 +142,7 @@ Below we describe several common approaches to plotting with Matplotlib. The pyplot API ^^^^^^^^^^^^^^ -`matplotlib.pyplot` is a collection of command style functions that make +`matplotlib.pyplot` is a collection of functions that make Matplotlib work like MATLAB. Each pyplot function makes some change to a figure: e.g., creates a figure, creates a plotting area in a figure, plots some lines in a plotting area, decorates the plot with labels, etc. From 961de9b887016317c536fdd9d27091dcd7ede550 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Thu, 18 Mar 2021 13:25:51 -0700 Subject: [PATCH 6/9] DOC: remove sentence --- doc/api/index.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/index.rst b/doc/api/index.rst index f1c008ac5c19..4750d078f3be 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -16,11 +16,6 @@ call their methods to add content and modify the apprearance. - :doc:`axes_api`: most plotting methods, Axes labels, access to axis styling, etc. - -(Note that there is also a parallel `matplotlib.pyplot` API interface -that is considered useful for interactive work; see -:ref:`usage patterns `, below). - Example: We create a Figure ``fig`` and Axes ``ax``. Then we call methods on them to plot data, add axis labels and a figure title. From 71fa50067a5ec8118f0e10a4026b91fc4303b47c Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sat, 20 Mar 2021 10:34:28 -0700 Subject: [PATCH 7/9] Fix plot --- doc/api/index.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/api/index.rst b/doc/api/index.rst index 4750d078f3be..41f5f32cdb2b 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -26,14 +26,15 @@ methods on them to plot data, add axis labels and a figure title. import matplotlib.pyplot as plt import numpy as np - x = np.arange(0, 4, 0.1) + x = np.arange(0, 4, 0.05) y = np.sin(x*np.pi) fig, ax = plt.subplots(figsize=(3,2), constrained_layout=True) ax.plot(x, y) ax.set_xlabel('t [s]') ax.set_ylabel('S [V]') - fig.suptitle('Sine wave') + ax.set_title('Sine wave') + fig.set_facecolor('lightsteelblue') Modules From e46ebc173a77ac9929618f2f9a54efd44e62f405 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 21 Mar 2021 15:10:40 -0700 Subject: [PATCH 8/9] FIX: style --- doc/api/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api/index.rst b/doc/api/index.rst index 41f5f32cdb2b..b317aecefa10 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -44,6 +44,7 @@ Alphabetical list of submodules: .. toctree:: :maxdepth: 1 + :class: multicol-toc matplotlib_configuration_api.rst afm_api.rst From 783f6069576e26e8c6dd9825619867bfe0d71b59 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 21 Mar 2021 19:18:02 -0700 Subject: [PATCH 9/9] FIX --- doc/api/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/api/index.rst b/doc/api/index.rst index b317aecefa10..eedb43289895 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -40,11 +40,10 @@ methods on them to plot data, add axis labels and a figure title. Modules ------- -Alphabetical list of submodules: +Alphabetical list of modules: .. toctree:: :maxdepth: 1 - :class: multicol-toc matplotlib_configuration_api.rst afm_api.rst