Merge pull request #154 from zmoon/docs

Document `draw_map()`

monet/plots/mapgen.py

@@ -1,10 +1,12 @@
-""" map utilities """
+"""Map utilities."""
+
 import cartopy.crs as ccrs
 import cartopy.feature as cfeature
 import matplotlib.pyplot as plt
 
 
 def draw_map(
+    *,
     crs=None,
     natural_earth=False,
     coastlines=True,
@@ -18,44 +20,58 @@ def draw_map(
     return_fig=False,
     **kwargs
 ):
-    """Short summary.
+    """Draw a map with Cartopy.
 
     Parameters
     ----------
-    ax : type
-        Description of parameter `ax` (the default is None).
+    crs : cartopy.crs.Projection
+        The map projection.
+        If set, this takes precedence over the possible ``kwargs['subplot_kw']['projection']``.
+        If unset (``None``), defaults to ``ccrs.PlateCarree()``.
     natural_earth : bool
-        Description of parameter `natural_earth` (the default is True).
+        Add the Cartopy Natural Earth ocean, land, lakes, and rivers features.
     coastlines : bool
-        Description of parameter `coastlines` (the default is True).
+        Add coastlines (`linewidth` applied).
     states : bool
-        Description of parameter `states` (the default is True).
+        Add states/provinces (`linewidth` applied).
+    counties : bool
+        Add US counties (`linewidth` applied).
     countries : bool
-        Description of parameter `countries` (the default is True).
-    state_resolutions : bool
-        Description of parameter `state_resolutions` (the default is '10m').
-    extent : [lon_min,lon_max,lat_min,lat_max]
-        Description of parameter `extent` (the default is None).
+        Add country borders (`linewidth` applied).
+    resolution : {'10m', '50m', '110m'}
+        The resolution of the Natural Earth features for coastlines, states, and counties.
+        The others are set automatically.
+    extent : array-like
+        Set the map extent with ``[lon_min,lon_max,lat_min,lat_max]``.
+    figsize : tuple
+        Figure size (width, height), passed to ``plt.subplots()``.
+        This takes precedence over the possible ``kwargs['figsize']``.
+    linewidth : float
+        Line width for coastlines, states, counties, and countries.
+    return_fig : bool
+        Return the figure and axes objects.
+        By default (``False``), just the axes object is returned.
+    **kwargs
+        Arguments pass to ``plt.subplots()``.
 
     Returns
     -------
-    type
-        Description of returned object.
-
+    :
+        By default, returns just the ``ax`` (:class:`cartopy.mpl.geoaxes.GeoAxes` instance).
+        If `return_fig` is true, returns ``fig, ax``.
     """
-    con2 = "subplot_kw" in kwargs and "projection" not in kwargs["subplot_kw"]
-    if kwargs is not None and crs is None:
-        if "subplot_kw" not in kwargs:
-            kwargs["subplot_kw"] = {"projection": ccrs.PlateCarree()}
-        elif con2:
-            kwargs["subplot_kw"]["projection"] = ccrs.PlateCarree()
-        f, ax = plt.subplots(figsize=figsize, **kwargs)
-    elif crs is not None:
-        f, ax = plt.subplots(figsize=figsize, subplot_kw={"projection": crs})
+    kwargs["figsize"] = figsize
+    if "subplot_kw" not in kwargs:
+        kwargs["subplot_kw"] = {}
+    if crs is not None:
+        kwargs["subplot_kw"]["projection"] = crs
     else:
-        f, ax = plt.subplots(figsize=figsize, subplot_kw={"projection": ccrs.PlateCarree()})
+        if "projection" not in kwargs["subplot_kw"]:
+            kwargs["subplot_kw"]["projection"] = ccrs.PlateCarree()
+
+    fig, ax = plt.subplots(**kwargs)
+
     if natural_earth:
-        # ax.stock_img()
         ax.add_feature(cfeature.OCEAN)
         ax.add_feature(cfeature.LAND)
         ax.add_feature(cfeature.LAKES)
@@ -68,7 +84,6 @@ def draw_map(
             scale=resolution,
             facecolor="none",
             edgecolor="k",
-            linewidth=linewidth,
         )
 
     if counties:
@@ -78,7 +93,6 @@ def draw_map(
             scale=resolution,
             facecolor="none",
             edgecolor="k",
-            linewidth=linewidth,
         )
 
     if coastlines:
@@ -97,6 +111,6 @@ def draw_map(
         ax.set_extent(extent)
 
     if return_fig:
-        return f, ax
+        return fig, ax
     else:
         return ax

tests/test_plot.py

@@ -6,6 +6,7 @@
 from packaging.version import Version
 
 import monet  # noqa: F401
+from monet.plots.mapgen import draw_map
 
 cartopy_version = Version(cartopy.__version__)
 
@@ -34,7 +35,12 @@ def test_quick_with_cartopy_ax(which):
     getattr(da.monet, f"quick_{which}")(ax=ax, transform=tran)
 
 
+def test_draw_map_counties():
+    _ = draw_map(counties=True, extent=[-110.5, -101, 36, 42])
+
+
 if __name__ == "__main__":
     test_quick("map")
+    test_draw_map_counties()
 
     plt.show()