Make the plotting API object oriented

doc/api.rst

@@ -3,60 +3,59 @@
 API Reference
 =============
 
-High-level functions for GMT modules
-------------------------------------
+.. currentmodule:: gmt
+
 
-Each GMT module (``gmt pscoast``, ``gmt psbasemap``, etc.) is wrapped by a
-function in the ``gmt`` top-level module.
+Plotting
+--------
+
+All plotting in GMT/Python is handled by the ``gmt.Figure`` class.
 
 .. autosummary::
     :toctree: api/
-    :template: function.rst
+    :template: class.rst
 
-    gmt.figure
-    gmt.show
-    gmt.psbasemap
-    gmt.pscoast
-    gmt.psconvert
-    gmt.psxy
+    Figure
 
 
-Additional utility functions:
+Utility functions
+-----------------
 
 .. autosummary::
     :toctree: api/
     :template: function.rst
 
-    gmt.test
+    test
 
 
 Low-level wrappers for the GMT C API
 ------------------------------------
 
-The GMT C API is accessed using ctypes_. The ``gmt.clib`` module offers
+The GMT C API is accessed using ctypes_. The ``gmt.clib`` package offers
 functions and classes that wrap the C API with a pythonic interface.
 
-Functions
-+++++++++
+
+Classes
++++++++
 
 .. autosummary::
     :toctree: api/
-    :template: function.rst
+    :template: class.rst
 
-    gmt.clib.call_module
-    gmt.clib.create_session
-    gmt.clib.destroy_session
-    gmt.clib.load_libgmt
-    gmt.clib.get_constant
+    clib.APISession
 
-Classes
-+++++++
+Functions
++++++++++
 
 .. autosummary::
     :toctree: api/
     :template: function.rst
 
-    gmt.clib.APISession
+    clib.call_module
+    clib.create_session
+    clib.destroy_session
+    clib.load_libgmt
+    clib.get_constant
 
 
 .. _ctypes: https://docs.python.org/3/library/ctypes.html

doc/first-steps.ipynb

@@ -13,6 +13,26 @@
     "The GMT modules are available as functions in the `gmt` Python package. See the [API Reference](api.html) for a list of all available functions."
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "False"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "dict(a='bbb', b='aa') == dict(a='bbb', b='aaa')"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -45,10 +65,10 @@
    "outputs": [],
    "source": [
     "# Start a new figure. \n",
-    "gmt.figure()\n",
+    "fig = gmt.Figure()\n",
     "# Create a Mercator map that is 6 inches wide\n",
-    "gmt.pscoast(R='-90/-70/0/20', J='M6i', G='chocolate', \n",
-    "            S='skyblue', P=True, B='afg')"
+    "fig.pscoast(R='-90/-70/0/20', J='M6i', G='chocolate', \n",
+    "            S='skyblue', B='afg')"
    ]
   },
   {
@@ -68,7 +88,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "gmt.show()"
+    "fig.show()"
    ]
   },
   {
@@ -83,12 +103,10 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
-    "help(gmt.pscoast)"
+    "help(fig.pscoast)"
    ]
   },
   {
@@ -107,11 +125,12 @@
    "outputs": [],
    "source": [
     "# Calling figure again creates a new figure\n",
-    "gmt.figure()\n",
-    "gmt.pscoast(region=[-90, -70, 0, 20], projection='M6i', \n",
-    "            land='chocolate', water='skyblue', \n",
-    "            portrait=True, frame='afg')\n",
-    "gmt.show()"
+    "fig_alias = gmt.Figure()\n",
+    "fig_alias.pscoast(\n",
+    "    region=[-90, -70, 0, 20], projection='M6i', \n",
+    "    land='chocolate', water='skyblue', \n",
+    "    frame='afg')\n",
+    "fig_alias.show()"
    ]
   },
   {
@@ -131,13 +150,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "gmt.figure()\n",
-    "gmt.pscoast(region=[130, 150, 35, 50], projection='M6i', \n",
-    "            frame='afg', shorelines=True,\n",
-    "            land='gray', water='lightblue',)\n",
-    "gmt.psxy(data='@tut_quakes.ngdc', style='c0.3c', \n",
-    "         color='blue', pen='faint', i='4,3')\n",
-    "gmt.show()"
+    "fig_quakes = gmt.Figure()\n",
+    "fig_quakes.pscoast(\n",
+    "    region=[130, 150, 35, 50], projection='M6i', \n",
+    "    frame='afg', shorelines=True, land='gray', \n",
+    "    water='lightblue')\n",
+    "fig_quakes.psxy(\n",
+    "    data='@tut_quakes.ngdc', style='c0.3c', color='blue', \n",
+    "    pen='faint', i='4,3')\n",
+    "fig_quakes.show()"
    ]
   },
   {

gmt/__init__.py

@@ -6,9 +6,8 @@
 from ._version import get_versions as _get_versions
 
 # Import modules to make the high-level GMT Python API
-from .session_management import figure, begin as _begin, end as _end
-from .ps_modules import psconvert, psbasemap, psxy, pscoast
-from .extra_modules import show
+from .session_management import begin as _begin, end as _end
+from .figure import Figure
 
 
 # Get the version number through versioneer