export and document using3D() function to ensure mplot3d is loaded (fixes #351)

Author: stevengj

README.md

@@ -174,7 +174,7 @@ If no Julia graphics backend is available when PyPlot is imported, then
 ### Choosing a Python GUI toolkit
 
 Only the [Tk](http://www.tcl.tk/), [wxWidgets](http://www.wxwidgets.org/),
-[GTK+](http://www.gtk.org/) (version 2 or 3), and [Qt](http://qt-project.org/) (version 4 or 5; via the PyQt5, 
+[GTK+](http://www.gtk.org/) (version 2 or 3), and [Qt](http://qt-project.org/) (version 4 or 5; via the PyQt5,
 [PyQt4](http://wiki.python.org/moin/PyQt4) or
 [PySide](http://qt-project.org/wiki/PySide)), Python GUI backends are
 supported by PyPlot.  (Obviously, you must have installed one of these
@@ -242,7 +242,9 @@ surf(rand(30,40))
 to plot a random 30×40 surface mesh.
 
 You can also explicitly create a subplot with 3d axes via, for
-example, `subplot(111, projection="3d")`, exactly as in Matplotlib.
+example, `subplot(111, projection="3d")`, exactly as in Matplotlib,
+but you must first call the `using3D()` function to ensure that
+mplot3d is loaded (this happens automatically for `plot3D` etc.).
 The `Axes3D` constructor and the
 [art3D](http://matplotlib.org/mpl_toolkits/mplot3d/api.html#art3d)
 module are also exported.

src/plot3d.jl

@@ -22,10 +22,21 @@ keys(m::LazyPyModule) = keys(PyObject(m))
 const axes3D = LazyPyModule("mpl_toolkits.mplot3d.axes3d")
 const art3D = LazyPyModule("mpl_toolkits.mplot3d.art3d")
 
+"""
+    using3D()
+
+This function ensures that the `mplot3d` module is loaded for 3d
+plotting.   This occurs automatically if you call any of the
+3d plotting functions like `plot3D` or `surf`, but it may be
+necessary to call this function manually if you are passing
+`projection="3d"` explicitly to axes or subplot objects.
+"""
+using3D() = (PyObject(axes3D); nothing)
+
 ###########################################################################
 # 3d plotting functions from mplot3d
 
-export art3D, Axes3D, surf, mesh, bar3D, contour3D, contourf3D, plot3D, plot_surface, plot_trisurf, plot_wireframe, scatter3D, text2D, text3D, zlabel, zlim, zscale, zticks
+export art3D, Axes3D, using3D, surf, mesh, bar3D, contour3D, contourf3D, plot3D, plot_surface, plot_trisurf, plot_wireframe, scatter3D, text2D, text3D, zlabel, zlim, zscale, zticks
 
 const mplot3d_funcs = (:bar3d, :contour3D, :contourf3D, :plot3D, :plot_surface,
                        :plot_trisurf, :plot_wireframe, :scatter3D,
@@ -34,7 +45,7 @@ const mplot3d_funcs = (:bar3d, :contour3D, :contourf3D, :plot3D, :plot_surface,
 for f in mplot3d_funcs
     fs = string(f)
     @eval @doc LazyHelp(axes3D,"Axes3D", $fs) function $f(args...; kws...)
-        PyObject(axes3D) # make sure mplot3d is loaded
+        using3D() # make sure mplot3d is loaded
         ax = gca(projection="3d")
         pycall(ax[$fs], PyAny, args...; kws...)
     end
@@ -50,7 +61,7 @@ const zlabel_funcs = (:zlabel, :zlim, :zscale, :zticks)
 for f in zlabel_funcs
     fs = string("set_", f)
     @eval @doc LazyHelp(axes3D,"Axes3D", $fs) function $f(args...; kws...)
-        PyObject(axes3D) # make sure mplot3d is loaded
+        using3D() # make sure mplot3d is loaded
         ax = gca(projection="3d")
         pycall(ax[$fs], PyAny, args...; kws...)
     end