From 735f3083635f67da2fd1b5d305a2806583244917 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 9 Jan 2018 09:46:35 -0800 Subject: [PATCH] Update docs, in particular for backends. --- doc-requirements.txt | 1 + doc/api/backend_agg_api.rst | 8 ++ doc/api/backend_cairo_api.rst | 8 ++ doc/api/backend_gtk3agg_api.rst | 11 +++ doc/api/backend_gtk3cairo_api.rst | 11 +++ doc/api/backend_gtkcairo_api.rst | 11 +++ doc/api/backend_managers_api.rst | 2 +- doc/api/backend_mixed_api.rst | 1 + doc/api/backend_nbagg_api.rst | 8 ++ doc/api/backend_pdf_api.rst | 1 + doc/api/backend_pgf_api.rst | 8 ++ doc/api/backend_ps_api.rst | 8 ++ doc/api/backend_qt4agg_api.rst | 1 - doc/api/backend_qt5agg_api.rst | 1 - doc/api/backend_svg_api.rst | 1 + doc/api/backend_tkagg_api.rst | 8 ++ doc/api/backend_tools_api.rst | 2 +- doc/api/backend_webagg_api.rst | 12 +++ doc/api/index_backend_api.rst | 17 ++-- doc/conf.py | 40 ++++----- examples/showcase/mandelbrot.py | 5 +- lib/matplotlib/backends/backend_cairo.py | 21 ++--- tutorials/introductory/usage.py | 102 +++++++++++------------ 23 files changed, 187 insertions(+), 101 deletions(-) create mode 100644 doc/api/backend_agg_api.rst create mode 100644 doc/api/backend_cairo_api.rst create mode 100644 doc/api/backend_gtk3agg_api.rst create mode 100644 doc/api/backend_gtk3cairo_api.rst create mode 100644 doc/api/backend_gtkcairo_api.rst create mode 100644 doc/api/backend_nbagg_api.rst create mode 100644 doc/api/backend_pgf_api.rst create mode 100644 doc/api/backend_ps_api.rst create mode 100644 doc/api/backend_tkagg_api.rst create mode 100644 doc/api/backend_webagg_api.rst diff --git a/doc-requirements.txt b/doc-requirements.txt index 6bae185bf850..8f5c6ef41845 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -9,6 +9,7 @@ sphinx>=1.3,!=1.5.0,!=1.6.4 colorspacious ipython +ipywidgets mock numpydoc>=0.4 pillow diff --git a/doc/api/backend_agg_api.rst b/doc/api/backend_agg_api.rst new file mode 100644 index 000000000000..40c8cd4bce6a --- /dev/null +++ b/doc/api/backend_agg_api.rst @@ -0,0 +1,8 @@ + +:mod:`matplotlib.backends.backend_agg` +====================================== + +.. automodule:: matplotlib.backends.backend_agg + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/api/backend_cairo_api.rst b/doc/api/backend_cairo_api.rst new file mode 100644 index 000000000000..2623270c6781 --- /dev/null +++ b/doc/api/backend_cairo_api.rst @@ -0,0 +1,8 @@ + +:mod:`matplotlib.backends.backend_cairo` +======================================== + +.. automodule:: matplotlib.backends.backend_cairo + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/api/backend_gtk3agg_api.rst b/doc/api/backend_gtk3agg_api.rst new file mode 100644 index 000000000000..b05498dee7d7 --- /dev/null +++ b/doc/api/backend_gtk3agg_api.rst @@ -0,0 +1,11 @@ + +:mod:`matplotlib.backends.backend_gtk3agg` +========================================== + +**TODO** We'll add this later, importing the gtk3 backends requires an active +X-session, which is not compatible with cron jobs. + +.. .. automodule:: matplotlib.backends.backend_gtk3agg +.. :members: +.. :undoc-members: +.. :show-inheritance: diff --git a/doc/api/backend_gtk3cairo_api.rst b/doc/api/backend_gtk3cairo_api.rst new file mode 100644 index 000000000000..b805af75e757 --- /dev/null +++ b/doc/api/backend_gtk3cairo_api.rst @@ -0,0 +1,11 @@ + +:mod:`matplotlib.backends.backend_gtk3cairo` +============================================ + +**TODO** We'll add this later, importing the gtk3 backends requires an active +X-session, which is not compatible with cron jobs. + +.. .. automodule:: matplotlib.backends.backend_gtk3cairo +.. :members: +.. :undoc-members: +.. :show-inheritance: diff --git a/doc/api/backend_gtkcairo_api.rst b/doc/api/backend_gtkcairo_api.rst new file mode 100644 index 000000000000..562f8ea6e7ce --- /dev/null +++ b/doc/api/backend_gtkcairo_api.rst @@ -0,0 +1,11 @@ + +:mod:`matplotlib.backends.backend_gtkcairo` +=========================================== + +**TODO** We'll add this later, importing the gtk backends requires an active +X-session, which is not compatible with cron jobs. + +.. .. automodule:: matplotlib.backends.backend_gtkcairo +.. :members: +.. :undoc-members: +.. :show-inheritance: diff --git a/doc/api/backend_managers_api.rst b/doc/api/backend_managers_api.rst index 86d1c383b966..faf4eda18de3 100644 --- a/doc/api/backend_managers_api.rst +++ b/doc/api/backend_managers_api.rst @@ -1,6 +1,6 @@ :mod:`matplotlib.backend_managers` -=================================== +================================== .. automodule:: matplotlib.backend_managers :members: diff --git a/doc/api/backend_mixed_api.rst b/doc/api/backend_mixed_api.rst index 9c55e4abaa7f..7457f6684f94 100644 --- a/doc/api/backend_mixed_api.rst +++ b/doc/api/backend_mixed_api.rst @@ -4,4 +4,5 @@ .. automodule:: matplotlib.backends.backend_mixed :members: + :undoc-members: :show-inheritance: diff --git a/doc/api/backend_nbagg_api.rst b/doc/api/backend_nbagg_api.rst new file mode 100644 index 000000000000..977eabce8db0 --- /dev/null +++ b/doc/api/backend_nbagg_api.rst @@ -0,0 +1,8 @@ + +:mod:`matplotlib.backends.backend_nbagg` +======================================== + +.. automodule:: matplotlib.backends.backend_nbagg + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/api/backend_pdf_api.rst b/doc/api/backend_pdf_api.rst index 115863d61875..ded143ddcf8d 100644 --- a/doc/api/backend_pdf_api.rst +++ b/doc/api/backend_pdf_api.rst @@ -4,4 +4,5 @@ .. automodule:: matplotlib.backends.backend_pdf :members: + :undoc-members: :show-inheritance: diff --git a/doc/api/backend_pgf_api.rst b/doc/api/backend_pgf_api.rst new file mode 100644 index 000000000000..ec7440080eb0 --- /dev/null +++ b/doc/api/backend_pgf_api.rst @@ -0,0 +1,8 @@ + +:mod:`matplotlib.backends.backend_pgf` +====================================== + +.. automodule:: matplotlib.backends.backend_pgf + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/api/backend_ps_api.rst b/doc/api/backend_ps_api.rst new file mode 100644 index 000000000000..9d585be7a0ad --- /dev/null +++ b/doc/api/backend_ps_api.rst @@ -0,0 +1,8 @@ + +:mod:`matplotlib.backends.backend_ps` +===================================== + +.. automodule:: matplotlib.backends.backend_ps + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/api/backend_qt4agg_api.rst b/doc/api/backend_qt4agg_api.rst index 2e2e852612c7..8bf490aa8cb9 100644 --- a/doc/api/backend_qt4agg_api.rst +++ b/doc/api/backend_qt4agg_api.rst @@ -6,4 +6,3 @@ :members: :undoc-members: :show-inheritance: - diff --git a/doc/api/backend_qt5agg_api.rst b/doc/api/backend_qt5agg_api.rst index 58e5353a32a9..8d1ad2aba0f0 100644 --- a/doc/api/backend_qt5agg_api.rst +++ b/doc/api/backend_qt5agg_api.rst @@ -6,4 +6,3 @@ :members: :undoc-members: :show-inheritance: - diff --git a/doc/api/backend_svg_api.rst b/doc/api/backend_svg_api.rst index 399042482ea8..0b26d11e8818 100644 --- a/doc/api/backend_svg_api.rst +++ b/doc/api/backend_svg_api.rst @@ -4,4 +4,5 @@ .. automodule:: matplotlib.backends.backend_svg :members: + :undoc-members: :show-inheritance: diff --git a/doc/api/backend_tkagg_api.rst b/doc/api/backend_tkagg_api.rst new file mode 100644 index 000000000000..2a55bfe5c693 --- /dev/null +++ b/doc/api/backend_tkagg_api.rst @@ -0,0 +1,8 @@ + +:mod:`matplotlib.backends.backend_tkagg` +======================================== + +.. automodule:: matplotlib.backends.backend_tkagg + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/api/backend_tools_api.rst b/doc/api/backend_tools_api.rst index 32babd5844b0..7e3d5619cc35 100644 --- a/doc/api/backend_tools_api.rst +++ b/doc/api/backend_tools_api.rst @@ -1,6 +1,6 @@ :mod:`matplotlib.backend_tools` -================================ +=============================== .. automodule:: matplotlib.backend_tools :members: diff --git a/doc/api/backend_webagg_api.rst b/doc/api/backend_webagg_api.rst new file mode 100644 index 000000000000..50070c3fcb68 --- /dev/null +++ b/doc/api/backend_webagg_api.rst @@ -0,0 +1,12 @@ + +:mod:`matplotlib.backends.backend_webagg` +========================================= + +.. note:: + The WebAgg backend is not documented here, in order to avoid adding Tornado + to the doc build requirements. + +.. .. automodule:: matplotlib.backends.backend_webagg +.. :members: +.. :undoc-members: +.. :show-inheritance: diff --git a/doc/api/index_backend_api.rst b/doc/api/index_backend_api.rst index 8588628c7c01..ce03c707e902 100644 --- a/doc/api/index_backend_api.rst +++ b/doc/api/index_backend_api.rst @@ -8,12 +8,19 @@ backends backend_managers_api.rst backend_mixed_api.rst backend_tools_api.rst + backend_agg_api.rst + backend_cairo_api.rst backend_gtkagg_api.rst + backend_gtkcairo_api.rst + backend_gtk3agg_api.rst + backend_gtk3cairo_api.rst + backend_nbagg_api.rst + backend_pdf_api.rst + backend_pgf_api.rst + backend_ps_api.rst backend_qt4agg_api.rst backend_qt5agg_api.rst - backend_wxagg_api.rst - backend_pdf_api.rst backend_svg_api.rst -.. backend_webagg.rst - dviread.rst - type1font.rst + backend_tkagg_api.rst + backend_webagg_api.rst + backend_wxagg_api.rst diff --git a/doc/conf.py b/doc/conf.py index c89c9d2c773a..45849d7538c2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -335,17 +335,8 @@ def _check_deps(): ] -class MyWX(MagicMock): - class Panel(object): - pass - - class ToolBar(object): - pass - - class Frame(object): - pass - - VERSION_STRING = '2.9' +class MyCairo(MagicMock): + version_info = (1, 4, 0) class MyPyQt4(MagicMock): @@ -450,14 +441,25 @@ def getapi(*args): return 1 -mockwxversion = MagicMock() -mockwx = MyWX() -mocksip = MySip() -mockpyqt4 = MyPyQt4() -sys.modules['wxversion'] = mockwxversion -sys.modules['wx'] = mockwx -sys.modules['sip'] = mocksip -sys.modules['PyQt4'] = mockpyqt4 +class MyWX(MagicMock): + class Panel(object): + pass + + class ToolBar(object): + pass + + class Frame(object): + pass + + VERSION_STRING = '2.9' + + +sys.modules['cairo'] = MyCairo() +sys.modules['cairo'].__name__ = 'cairocffi' +sys.modules['PyQt4'] = MyPyQt4() +sys.modules['sip'] = MySip() +sys.modules['wx'] = MyWX() +sys.modules['wxversion'] = MagicMock() # numpydoc config diff --git a/examples/showcase/mandelbrot.py b/examples/showcase/mandelbrot.py index ed43a087b18f..e8a4366afacd 100644 --- a/examples/showcase/mandelbrot.py +++ b/examples/showcase/mandelbrot.py @@ -67,10 +67,9 @@ def mandelbrot_set(xmin, xmax, ymin, ymax, xn, yn, maxiter, horizon=2.0): # Some advertisement for matplotlib year = time.strftime("%Y") - major, minor, micro = matplotlib.__version__.split('.', 2) text = ("The Mandelbrot fractal set\n" - "Rendered with matplotlib %s.%s, %s - http://matplotlib.org" - % (major, minor, year)) + "Rendered with matplotlib %s, %s - http://matplotlib.org" + % (matplotlib.__version__, year)) ax.text(xmin+.025, ymin+.025, text, color="white", fontsize=12, alpha=0.5) plt.show() diff --git a/lib/matplotlib/backends/backend_cairo.py b/lib/matplotlib/backends/backend_cairo.py index 0c4c89ae2c4f..39311a439330 100644 --- a/lib/matplotlib/backends/backend_cairo.py +++ b/lib/matplotlib/backends/backend_cairo.py @@ -1,21 +1,10 @@ """ A Cairo backend for matplotlib -Author: Steve Chaplin - -Cairo is a vector graphics library with cross-device output support. -Features of Cairo: - * anti-aliasing - * alpha channel - * saves image files as PNG, PostScript, PDF - -http://cairographics.org -Requires (in order, all available from Cairo website): - cairo, pycairo - -Naming Conventions - * classes MixedUpperCase - * varables lowerUpper - * functions underscore_separated +============================== +:Author: Steve Chaplin and others + +This backend depends on `cairo `_, and either on +cairocffi, or (Python 2 only) on pycairo. """ from __future__ import (absolute_import, division, print_function, diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py index a6cade14fe2d..b521102af9aa 100644 --- a/tutorials/introductory/usage.py +++ b/tutorials/introductory/usage.py @@ -321,14 +321,19 @@ def my_plotter(ax, data1, data2, param_dict): # # backend : WXAgg # use wxpython with antigrain (agg) rendering # -# #. Setting the :envvar:`MPLBACKEND` environment -# variable, either for your current shell or for a single script:: +# #. Setting the :envvar:`MPLBACKEND` environment variable, either for your +# current shell or for a single script. On Unix:: # -# > export MPLBACKEND="module://my_backend" +# > export MPLBACKEND=module://my_backend # > python simple_plot.py # # > MPLBACKEND="module://my_backend" python simple_plot.py # +# On Windows, only the former is possible:: +# +# > set MPLBACKEND=module://my_backend +# > python simple_plot.py +# # Setting this environment variable will override the ``backend`` parameter # in *any* ``matplotlibrc``, even if there is a ``matplotlibrc`` in your # current working directory. Therefore setting :envvar:`MPLBACKEND` @@ -397,11 +402,10 @@ def my_plotter(ax, data1, data2, param_dict): # `Portable Document Format`_ # SVG :term:`svg` :term:`vector graphics` -- # `Scalable Vector Graphics`_ -# :term:`Cairo` :term:`png` :term:`vector graphics` -- -# :term:`ps` `Cairo graphics`_ -# :term:`pdf` +# :term:`Cairo` :term:`png` :term:`raster graphics` and +# :term:`ps` :term:`vector graphics` -- using the +# :term:`pdf` `Cairo graphics`_ library # :term:`svg` -# ... # ============= ============ ================================================ # # And here are the user interfaces and renderer combinations supported; @@ -409,53 +413,46 @@ def my_plotter(ax, data1, data2, param_dict): # and of using appropriate renderers from the table above to write to # a file: # -# ============ ================================================================ -# Backend Description -# ============ ================================================================ -# Qt5Agg Agg rendering in a :term:`Qt5` canvas (requires PyQt5_). This -# backend can be activated in IPython with ``%matplotlib qt5``. -# ipympl Agg rendering embedded in a Jupyter widget. (requires ipympl) -# This can be enabled in a Jupyter notebook with -# ``%matplotlib ipympl`` -# GTK3Agg Agg rendering to a :term:`GTK` 3.x canvas (requires PyGObject_ -# and pycairo_ or cairocffi_) -# This backend can be activated in IPython with -# ``%matplotlib gtk3``. -# macosx Agg rendering into a Cocoa canvas in OSX. -# This backend can be activated in IPython with -# ``%matplotlib osx``. -# TkAgg Agg rendering to a :term:`Tk` canvas (requires TkInter_). -# This backend can be activated in IPython with -# ``%matplotlib tk``. -# nbAgg Embed an interactive figure in a Jupyter classic notebook. This -# backend can be enabled in Jupyter notebooks via -# ``%matplotlib notebook``. -# WebAgg On ``show()`` will start a tornado server with an interactive -# figure. -# GTK3Cairo Cairo rendering to a :term:`GTK` 3.x canvas (requires PyGObject_ -# and pycairo_ or cairocffi_) -# Qt4Agg Agg rendering to a :term:`Qt4` canvas (requires PyQt4_ -# or ``pyside``). -# This backend can be activated in IPython with -# ``%matplotlib qt4``. -# GTKAgg Agg rendering to a :term:`GTK` 2.x canvas (requires PyGTK_ and -# pycairo_ or cairocffi_; Python2 only) -# This backend can be activated in IPython with -# ``%matplotlib gtk``. -# GTKCairo Cairo rendering to a :term:`GTK` 2.x canvas (requires PyGTK_ -# and pycairo_ or cairocffi_; Python2 only) -# WXAgg Agg rendering to a :term:`wxWidgets` canvas -# (requires wxPython_. v4.0 (in beta) is -# required for python3). -# This backend can be activated in IPython with -# ``%matplotlib wx``. -# ============ ================================================================ +# ========= ================================================================ +# Backend Description +# ========= ================================================================ +# Qt5Agg Agg rendering in a :term:`Qt5` canvas (requires PyQt5_). This +# backend can be activated in IPython with ``%matplotlib qt5``. +# ipympl Agg rendering embedded in a Jupyter widget. (requires ipympl). +# This backend can be enabled in a Jupyter notebook with +# ``%matplotlib ipympl``. +# GTK3Agg Agg rendering to a :term:`GTK` 3.x canvas (requires PyGObject_, +# and pycairo_ or cairocffi_). This backend can be activated in +# IPython with ``%matplotlib gtk3``. +# macosx Agg rendering into a Cocoa canvas in OSX. This backend can be +# activated in IPython with ``%matplotlib osx``. +# TkAgg Agg rendering to a :term:`Tk` canvas (requires TkInter_). This +# backend can be activated in IPython with ``%matplotlib tk``. +# nbAgg Embed an interactive figure in a Jupyter classic notebook. This +# backend can be enabled in Jupyter notebooks via +# ``%matplotlib notebook``. +# WebAgg On ``show()`` will start a tornado server with an interactive +# figure. +# GTK3Cairo Cairo rendering to a :term:`GTK` 3.x canvas (requires PyGObject_, +# and pycairo_ or cairocffi_). +# Qt4Agg Agg rendering to a :term:`Qt4` canvas (requires PyQt4_ or +# ``pyside``). This backend can be activated in IPython with +# ``%matplotlib qt4``. +# GTKAgg Agg rendering to a :term:`GTK` 2.x canvas (requires PyGTK_, and +# pycairo_ or cairocffi_; Python2 only). This backend can be +# activated in IPython with ``%matplotlib gtk``. +# GTKCairo Cairo rendering to a :term:`GTK` 2.x canvas (requires PyGTK_, +# and pycairo_ or cairocffi_; Python2 only). +# WXAgg Agg rendering to a :term:`wxWidgets` canvas (requires wxPython_; +# v4.0 (in beta) is required for Python3). This backend can be +# activated in IPython with ``%matplotlib wx``.# +# ========= ================================================================ # # .. _`Anti-Grain Geometry`: http://antigrain.com/ # .. _Postscript: https://en.wikipedia.org/wiki/PostScript # .. _`Portable Document Format`: https://en.wikipedia.org/wiki/Portable_Document_Format # .. _`Scalable Vector Graphics`: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics -# .. _`Cairo graphics`: https://en.wikipedia.org/wiki/Cairo_(graphics) +# .. _`Cairo graphics`: https://wwW.cairographics.org # .. _`Gimp Drawing Kit`: https://en.wikipedia.org/wiki/GDK # .. _PyGTK: http://www.pygtk.org # .. _PyGObject: https://wiki.gnome.org/action/show/Projects/PyGObject @@ -489,11 +486,8 @@ def my_plotter(ax, data1, data2, param_dict): # GTK and Cairo # ------------- # -# Both `GTK2` and `GTK3` have implicit dependencies on PyCairo regardless of the -# specific Matplotlib backend used. Unfortunatly the latest release of PyCairo -# for Python3 does not implement the Python wrappers needed for the `GTK3Agg` -# backend. `Cairocffi` can be used as a replacement which implements the correct -# wrapper. +# Both `GTK2` and `GTK3` depend on a Cairo wrapper (PyCairo or cairocffi) even +# if the Agg renderer is used. On Python3, only cairocffi is supported. # # How do I select PyQt4 or PySide? # --------------------------------