From ac7e8309aa3dc9573229b2d95f88338a1b1a6ef0 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 17 Jun 2018 19:29:41 +0200 Subject: [PATCH] Cleanup Matplotlib API docs --- doc/_templates/layout.html | 2 +- doc/api/api_overview.rst | 55 ++++++++++++++++++++++++++++++++++++++ doc/api/index.rst | 26 +++++++----------- doc/api/pyplot_summary.rst | 32 +++++++--------------- doc/contents.rst | 3 +-- doc/users/index.rst | 2 +- 6 files changed, 78 insertions(+), 42 deletions(-) create mode 100644 doc/api/api_overview.rst diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index 7e1b67f7ff42..7129a559cbef 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -40,7 +40,7 @@

{{ _('Navigation') }}

  • home| 
  • examples| 
  • tutorials| 
    • -
  • pyplot| 
    • +
  • API| 
  • docs »
    • {%- for parent in parents %} diff --git a/doc/api/api_overview.rst b/doc/api/api_overview.rst new file mode 100644 index 000000000000..0b735010cbdb --- /dev/null +++ b/doc/api/api_overview.rst @@ -0,0 +1,55 @@ +API Overview +============ + +Below we describe several common approaches to plotting with Matplotlib. + +.. contents:: + +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 ` + +The object-oriented API +----------------------- + +At its core, Matbplotlib 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) +--------------------------- + +.. warning:: + Since heavily importing into the global namespace may result in unexpected + behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot` + instead. + +`matplotlib.pylab` is a module that includes `matplotlib.pyplot`, `numpy` +and some additional functions within a single namespace. It's original puropse +was to mimic a MATLAB-like way of working by importing all functions into the +global namespace. This is considered bad style nowadays. diff --git a/doc/api/index.rst b/doc/api/index.rst index 685d2f457cff..2646cb783bcd 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -4,17 +4,20 @@ The Matplotlib API #################### -.. only:: html +.. toctree:: + :maxdepth: 1 + + api_overview.rst + api_changes.rst - :Release: |version| - :Date: |today| +Modules +======= .. toctree:: :maxdepth: 1 - pyplot_summary.rst - api_changes.rst matplotlib_configuration_api.rst + pyplot_summary.rst afm_api.rst animation_api.rst artist_api.rst @@ -60,22 +63,13 @@ units_api.rst widgets_api.rst -.. currentmodule:: matplotlib - -.. autosummary:: - :toctree: _as_gen - :template: autofunctions.rst - - pyplot - - Toolkits --------- +======== .. toctree:: :maxdepth: 1 - + toolkits/index.rst toolkits/mplot3d.rst toolkits/axes_grid1.rst toolkits/axisartist.rst diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst index 99660f45864d..95f516935837 100644 --- a/doc/api/pyplot_summary.rst +++ b/doc/api/pyplot_summary.rst @@ -1,33 +1,19 @@ -Below we describe several common approaches to plotting with Matplotlib. +Pyplot function overview +------------------------ -.. contents:: +.. currentmodule:: matplotlib -The Pyplot API --------------- +.. autosummary:: + :toctree: _as_gen + :template: autofunctions.rst + + pyplot -The :mod:`matplotlib.pyplot` module contains functions that allow you to generate -many kinds of plots quickly. For examples that showcase the use -of the :mod:`matplotlib.pyplot` module, see the -:doc:`/tutorials/introductory/pyplot` -or the :ref:`pyplots_examples`. We also recommend that you look into -the object-oriented approach to plotting, described below. .. currentmodule:: matplotlib.pyplot .. autofunction:: plotting -The Object-Oriented API ------------------------ - -Most of these functions also exist as methods in the -:class:`matplotlib.axes.Axes` class. You can use them with the -"Object Oriented" approach to Matplotlib. - -While it is easy to quickly generate plots with the -:mod:`matplotlib.pyplot` module, -we recommend using the object-oriented approach for more control -and customization of your plots. See the methods in the -:meth:`matplotlib.axes.Axes` class for many of the same plotting functions. Colors in Matplotlib -------------------- @@ -38,4 +24,6 @@ Below we list several ways in which color can be utilized in Matplotlib. For a more in-depth look at colormaps, see the :doc:`/tutorials/colors/colormaps` tutorial. +.. currentmodule:: matplotlib.pyplot + .. autofunction:: colormaps diff --git a/doc/contents.rst b/doc/contents.rst index 140b365b6ca5..8102de243339 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -16,10 +16,9 @@ Overview users/index.rst faq/index.rst - api/toolkits/index.rst + api/index.rst resources/index.rst thirdpartypackages/index.rst - api/index.rst devel/index.rst glossary/index.rst diff --git a/doc/users/index.rst b/doc/users/index.rst index 3dd0ed44f74b..60eaf7fb6d4a 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -12,11 +12,11 @@ User's Guide .. toctree:: :maxdepth: 2 - history.rst installing.rst ../tutorials/index.rst interactive.rst whats_new.rst + history.rst github_stats.rst license.rst credits.rst