update docstrings

gboeing · Jun 23, 2023 · 908d5f9 · 908d5f9
1 parent c1ca9cd
commit 908d5f9
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 56 deletions.
diff --git a/osmnx/geometries.py b/osmnx/geometries.py
@@ -1,11 +1,11 @@
 """
-Download geospatial features' geometries and attributes from OpenStreetMap.
+Download OpenStreetMap geospatial features' geometries and attributes.
 
 Retrieve points of interest, building footprints, transit lines/stops, or any
-other objects from OSM, including their geometries and attribute data, and
+other features from OSM, including their geometries and attribute data, and
 construct a GeoDataFrame of them. You can use this module to query for nodes,
 ways, and relations (the latter of type "multipolygon" or "boundary" only) by
-passing a dictionary of desired tags/values.
+passing a dictionary of desired OSM tags.
 """
 
 import logging as lg
@@ -77,6 +77,10 @@ def geometries_from_bbox(north, south, east, west, tags):
     """
     Create a GeoDataFrame of OSM features within a N, S, E, W bounding box.
 
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
+
     Parameters
     ----------
     north : float
@@ -103,11 +107,6 @@ def geometries_from_bbox(north, south, east, west, tags):
     Returns
     -------
     gdf : geopandas.GeoDataFrame
-
-    Notes
-    -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module.
     """
     # convert bounding box to a polygon
     polygon = utils_geo.bbox_to_poly(north, south, east, west)
@@ -122,6 +121,10 @@ def geometries_from_point(center_point, tags, dist=1000):
     """
     Create GeoDataFrame of OSM features within some distance N, S, E, W of a point.
 
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
+
     Parameters
     ----------
     center_point : tuple
@@ -144,11 +147,6 @@ def geometries_from_point(center_point, tags, dist=1000):
     Returns
     -------
     gdf : geopandas.GeoDataFrame
-
-    Notes
-    -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module.
     """
     # create bounding box from center point and distance in each direction
     north, south, east, west = utils_geo.bbox_from_point(center_point, dist)
@@ -166,6 +164,10 @@ def geometries_from_address(address, tags, dist=1000):
     """
     Create GeoDataFrame of OSM features within some distance N, S, E, W of address.
 
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
+
     Parameters
     ----------
     address : string
@@ -189,11 +191,6 @@ def geometries_from_address(address, tags, dist=1000):
     Returns
     -------
     gdf : geopandas.GeoDataFrame
-
-    Notes
-    -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module.
     """
     # geocode the address string to a (lat, lng) point
     center_point = geocoder.geocode(query=address)
@@ -206,7 +203,7 @@ def geometries_from_address(address, tags, dist=1000):
 
 def geometries_from_place(query, tags, which_result=None, buffer_dist=None):
     """
-    Create GeoDataFrame of OSM features within boundaries of geocodable place(s).
+    Create GeoDataFrame of OSM features within boundaries of some place(s).
 
     The query must be geocodable and OSM must have polygon boundaries for the
     geocode result. If OSM does not have a polygon for this place, you can
@@ -221,6 +218,10 @@ def geometries_from_place(query, tags, which_result=None, buffer_dist=None):
     geocode_to_gdf function, then pass it to the geometries_from_polygon
     function.
 
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
+
     Parameters
     ----------
     query : string or dict or list
@@ -246,11 +247,6 @@ def geometries_from_place(query, tags, which_result=None, buffer_dist=None):
     Returns
     -------
     gdf : geopandas.GeoDataFrame
-
-    Notes
-    -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module.
     """
     # create a GeoDataFrame with the spatial boundaries of the place(s)
     if isinstance(query, (str, dict)):
@@ -279,6 +275,10 @@ def geometries_from_polygon(polygon, tags):
     """
     Create GeoDataFrame of OSM features within boundaries of a (multi)polygon.
 
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
+
     Parameters
     ----------
     polygon : shapely.geometry.Polygon or shapely.geometry.MultiPolygon
@@ -299,11 +299,6 @@ def geometries_from_polygon(polygon, tags):
     Returns
     -------
     gdf : geopandas.GeoDataFrame
-
-    Notes
-    -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module.
     """
     # verify that the geometry is valid and a Polygon/MultiPolygon
     if not polygon.is_valid:

diff --git a/osmnx/graph.py b/osmnx/graph.py
@@ -1,4 +1,4 @@
-"""Graph creation functions."""
+"""Download and create graphs from OpenStreetMap data."""
 
 import itertools
 from warnings import warn
@@ -36,7 +36,11 @@ def graph_from_bbox(
     custom_filter=None,
 ):
     """
-    Create a graph from OSM within some bounding box.
+    Download and create a graph within some bounding box.
+
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
 
     Parameters
     ----------
@@ -73,10 +77,9 @@ def graph_from_bbox(
 
     Notes
     -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module. Very large query areas
-    will use the utils_geo._consolidate_subdivide_geometry function to perform
-    multiple queries: see that function's documentation for caveats.
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
     """
     # convert bounding box to a polygon
     polygon = utils_geo.bbox_to_poly(north, south, east, west)
@@ -108,7 +111,11 @@ def graph_from_point(
     custom_filter=None,
 ):
     """
-    Create a graph from OSM within some distance of some (lat, lng) point.
+    Download and create a graph within some distance of a (lat, lng) point.
+
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
 
     Parameters
     ----------
@@ -147,10 +154,9 @@ def graph_from_point(
 
     Notes
     -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module. Very large query areas
-    will use the utils_geo._consolidate_subdivide_geometry function to perform
-    multiple queries: see that function's documentation for caveats.
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
     """
     if dist_type not in {"bbox", "network"}:  # pragma: no cover
         raise ValueError('dist_type must be "bbox" or "network"')
@@ -195,7 +201,11 @@ def graph_from_address(
     custom_filter=None,
 ):
     """
-    Create a graph from OSM within some distance of some address.
+    Download and create a graph within some distance of an address.
+
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
 
     Parameters
     ----------
@@ -237,10 +247,9 @@ def graph_from_address(
 
     Notes
     -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module. Very large query areas
-    will use the utils_geo._consolidate_subdivide_geometry function to perform
-    multiple queries: see that function's documentation for caveats.
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
     """
     # geocode the address string to a (lat, lng) point
     point = geocoder.geocode(query=address)
@@ -277,7 +286,7 @@ def graph_from_place(
     custom_filter=None,
 ):
     """
-    Create graph from OSM within the boundaries of some geocodable place(s).
+    Download and create a graph within the boundaries of some place(s).
 
     The query must be geocodable and OSM must have polygon boundaries for the
     geocode result. If OSM does not have a polygon for this place, you can
@@ -291,6 +300,10 @@ def graph_from_place(
     the OSM ID of the place, you can retrieve its boundary polygon using the
     geocode_to_gdf function, then pass it to the graph_from_polygon function.
 
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
+
     Parameters
     ----------
     query : string or dict or list
@@ -325,10 +338,9 @@ def graph_from_place(
 
     Notes
     -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module. Very large query areas
-    will use the utils_geo._consolidate_subdivide_geometry function to perform
-    multiple queries: see that function's documentation for caveats.
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
     """
     # create a GeoDataFrame with the spatial boundaries of the place(s)
     if isinstance(query, (str, dict)):
@@ -372,7 +384,11 @@ def graph_from_polygon(
     custom_filter=None,
 ):
     """
-    Create a graph from OSM within the boundaries of some shapely polygon.
+    Download and create a graph within the boundaries of a (multi)polygon.
+
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings.
 
     Parameters
     ----------
@@ -404,10 +420,9 @@ def graph_from_polygon(
 
     Notes
     -----
-    You can configure the Overpass server timeout, memory allocation, and
-    other custom settings via the `settings` module. Very large query areas
-    will use the utils_geo._consolidate_subdivide_geometry function to perform
-    multiple queries: see that function's documentation for caveats.
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
     """
     # verify that the geometry is valid and is a shapely Polygon/MultiPolygon
     # before proceeding

diff --git a/osmnx/plot.py b/osmnx/plot.py
@@ -1,4 +1,4 @@
-"""Visualize spatial footprints, street networks, routes, and orientations."""
+"""Visualize street networks, routes, orientations, and geospatial features."""
 
 from pathlib import Path