Merge pull request #10203 from anntzer/doc-update

jklymak · web-flow · commit 364d4ca3e04f · 2018-01-19T09:15:19.000-08:00
Update docs, in particular for backends.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <http://cairographics.org>`_, 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
