Merge pull request #1116 from gboeing/docs

improve documentation

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
 
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 2
 

.github/workflows/test-minimal.yml

@@ -20,7 +20,7 @@ jobs:
 
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 2
 

.pre-commit-config.yaml

@@ -30,7 +30,7 @@ repos:
         types_or: [markdown, yaml]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.1.13"
+    rev: "v0.1.15"
     hooks:
       - id: ruff
         args: [--fix]

CHANGELOG.md

@@ -3,7 +3,8 @@
 ## 2.0.0 (Unreleased)
 
 - add type annotations to all public and private functions throughout the package (#1107)
-- remove functionality previously deprecated in v1 (#1113)
+- improve docstrings throughout the package (#1116)
+- remove functionality previously deprecated in v1 (#1113 #1122)
 - drop Python 3.8 support (#1106)
 - increase add_node_elevations_google default batch_size to 512 to match Google's limit (#1115)
 - make which_result function parameter consistently able to accept a list throughout package (#1113)
@@ -17,12 +18,15 @@
 
 ## 1.9.0 (Unreleased)
 
+- add endpoint_attrs argument to simplification.simplify_graph function to flexibly relax strictness (#1117)
 - fix a bug in the features module's polygon handling (#1104)
 - update obsolete numpy random number generation (#1108)
 - update warning messages to note that deprecated code will be removed in v2.0.0 (#1111)
+- deprecate strict argument in simplification.simplify_graph function in favor of new endpoint_attrs argument (#1117)
 - deprecate north, south, east, west arguments throughout package in favor of bbox tuple argument (#1112)
 - deprecate return_coords argument in graph.graph_from_address function (#1105)
 - deprecate return_hex argument in plot.get_colors function (#1109)
+- deprecate address, point, network_type, edge_color, and smooth_joints arguments in plot.plot_figure_ground function (#1121)
 
 ## 1.8.1 (2023-12-31)
 

docs/requirements.txt

@@ -1,2 +1,3 @@
 furo
 sphinx == 7.*  # same value as needs_sphinx in /docs/source/conf.py
+sphinx-autodoc-typehints

docs/source/conf.py

@@ -37,10 +37,17 @@
     "sklearn",
 ]
 
+autodoc_typehints = "description"
+napoleon_use_param = True
+napoleon_use_rtype = False
+typehints_document_rtype = True
+typehints_use_rtype = False
+typehints_fully_qualified = False
+
 # general configuration and options for HTML output
 # see https://www.sphinx-doc.org/en/master/usage/configuration.html
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_autodoc_typehints"]
 html_static_path: list[str] = []
 html_theme = "furo"
 language = "en"

environments/docker/requirements.txt

@@ -23,6 +23,7 @@ statsmodels
 # docs
 furo
 sphinx
+sphinx-autodoc-typehints
 
 # packaging
 conda-smithy

osmnx/_errors.py

@@ -2,7 +2,7 @@
 
 
 class CacheOnlyInterruptError(InterruptedError):
-    """Exception for settings.cache_only_mode=True interruption."""
+    """Exception for `settings.cache_only_mode=True` interruption."""
 
 
 class GraphSimplificationError(ValueError):

osmnx/_http.py

@@ -42,12 +42,12 @@ def _save_to_cache(
 
     Parameters
     ----------
-    url : string
-        the URL of the request
-    response_json : dict or list
-        the JSON response
-    ok : bool
-        requests response.ok value
+    url
+        The URL of the request.
+    response_json
+        The JSON response from the server.
+    ok
+        A `requests.response.ok` value.
 
     Returns
     -------
@@ -80,13 +80,13 @@ def _url_in_cache(url: str) -> Path | None:
 
     Parameters
     ----------
-    url : string
-        the URL to look for in the cache
+    url
+        The URL to look for in the cache.
 
     Returns
     -------
-    filepath : pathlib.Path
-        path to cached response for url if it exists, otherwise None
+    filepath
+        Path to cached response for `url` if it exists, otherwise None.
     """
     # hash the url to generate the cache filename
     filename = sha1(url.encode("utf-8")).hexdigest() + ".json"
@@ -100,20 +100,20 @@ def _retrieve_from_cache(
     url: str, check_remark: bool = True
 ) -> dict[str, Any] | list[dict[str, Any]] | None:
     """
-    Retrieve a HTTP response JSON object from the cache, if it exists.
+    Retrieve a HTTP response JSON object from the cache if it exists.
 
     Parameters
     ----------
-    url : string
-        the URL of the request
-    check_remark : bool
-        if True, only return filepath if cached response does not have a
-        remark key indicating a server warning
+    url
+        The URL of the request.
+    check_remark
+        If True, only return filepath if cached response does not have a
+        remark key indicating a server warning.
 
     Returns
     -------
-    response_json : dict or list
-        cached response for url if it exists in the cache, otherwise None
+    response_json
+        Cached response for `url` if it exists in the cache, otherwise None.
     """
     # if the tool is configured to use the cache
     if settings.use_cache:
@@ -148,17 +148,17 @@ def _get_http_headers(
 
     Parameters
     ----------
-    user_agent : string
-        the user agent string, if None will set with OSMnx default
-    referer : string
-        the referer string, if None will set with OSMnx default
-    accept_language : string
-        make accept-language explicit e.g. for consistent nominatim result
-        sorting
+    user_agent
+        The user agent string. If None, use the OSMnx default.
+    referer
+        The referer string. If None, use the OSMnx default.
+    accept_language
+        The accept language. Make it explicit for consistent Nominatim result
+        sorting.
 
     Returns
     -------
-    headers : dict
+    headers
     """
     if user_agent is None:
         user_agent = settings.default_user_agent
@@ -187,13 +187,13 @@ def _resolve_host_via_doh(hostname: str) -> str:
 
     Parameters
     ----------
-    hostname : string
-        the hostname to consistently resolve the IP address of
+    hostname
+        The hostname to consistently resolve the IP address of.
 
     Returns
     -------
-    ip_address : string
-        resolved IP address of host, or hostname itself if resolution failed
+    ip_address
+        Resolved IP address of host, or hostname itself if resolution failed.
     """
     if settings.doh_url_template is None:
         # if user has set the url template to None, return hostname itself
@@ -243,8 +243,8 @@ def _config_dns(url: str) -> None:
 
     Parameters
     ----------
-    url : string
-        the URL to consistently resolve the IP address of
+    url
+        The URL to consistently resolve the IP address of.
 
     Returns
     -------
@@ -279,13 +279,13 @@ def _hostname_from_url(url: str) -> str:
 
     Parameters
     ----------
-    url : string
-        the url from which to extract the hostname
+    url
+        The url from which to extract the hostname.
 
     Returns
     -------
-    hostname : string
-        the extracted hostname (domain)
+    hostname
+        The extracted hostname (domain).
     """
     return urlparse(url).netloc.split(":")[0]
 
@@ -296,12 +296,12 @@ def _parse_response(response: requests.Response) -> dict[str, Any] | list[dict[s
 
     Parameters
     ----------
-    response : requests.response
-        the response object
+    response
+        The response object.
 
     Returns
     -------
-    response_json : dict or list
+    response_json
         Value will be a dict if the response is from the Google or Overpass
         APIs, and a list if the response is from the Nominatim API.
     """

osmnx/_nominatim.py

@@ -26,19 +26,18 @@ def _download_nominatim_element(
 
     Parameters
     ----------
-    query : string or dict
-        query string or structured query dict
-    by_osmid : bool
-        if True, treat query as an OSM ID lookup rather than text search
-    limit : int
-        max number of results to return
-    polygon_geojson : bool
-        whether to retrieve the place's geometry from the API
+    query
+        Query string or structured query dict.
+    by_osmid
+        If True, treat `query` as an OSM ID lookup rather than text search.
+    limit
+        Max number of results to return.
+    polygon_geojson
+        Whether to retrieve the place's geometry from the API.
 
     Returns
     -------
-    response_json : list
-        JSON response from the Nominatim server
+    response_json
     """
     # define the parameters
     params: OrderedDict[str, int | str] = OrderedDict()
@@ -87,19 +86,20 @@ def _nominatim_request(
 
     Parameters
     ----------
-    params : OrderedDict
-        key-value pairs of parameters
-    request_type : string {"search", "reverse", "lookup"}
-        which Nominatim API endpoint to query
-    pause : float
-        how long to pause before request, in seconds. per the nominatim usage
-        policy: "an absolute maximum of 1 request per second" is allowed
-    error_pause : float
-        how long to pause in seconds before re-trying request if error
+    params
+        Key-value pairs of parameters.
+    request_type
+        {"search", "reverse", "lookup"}
+        Which Nominatim API endpoint to query.
+    pause
+        How long to pause before request, in seconds. Per the Nominatim usage
+        policy: "an absolute maximum of 1 request per second" is allowed.
+    error_pause
+        How long to pause in seconds before re-trying request if error.
 
     Returns
     -------
-    response_json : list
+    response_json
     """
     if request_type not in {"search", "reverse", "lookup"}:  # pragma: no cover
         msg = 'Nominatim request_type must be "search", "reverse", or "lookup"'