From e4c5a6b07355151da28375b5b8bd829e01614288 Mon Sep 17 00:00:00 2001
From: Geoff Boeing <boeing@usc.edu>
Date: Thu, 16 Jan 2025 12:20:58 -0800
Subject: [PATCH] add numpydoc validation to pre-commit

---
 .pre-commit-config.yaml        | 5 +++++
 environments/make-env-files.py | 3 ++-
 osmnx/convert.py               | 1 -
 osmnx/features.py              | 4 ++--
 osmnx/graph.py                 | 3 ---
 osmnx/plot.py                  | 6 +++---
 osmnx/projection.py            | 2 +-
 osmnx/routing.py               | 2 +-
 pyproject.toml                 | 3 +++
 9 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 8d6ae3c2..f27c2792 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -29,6 +29,11 @@ repos:
       - id: yamllint
         args: [--strict, --config-file=./tests/.yamllint.yml]
 
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.8.0
+    hooks:
+      - id: numpydoc-validation
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.9.1
     hooks:
diff --git a/environments/make-env-files.py b/environments/make-env-files.py
index 97f83fcd..440ac43f 100644
--- a/environments/make-env-files.py
+++ b/environments/make-env-files.py
@@ -38,7 +38,7 @@ def make_requirement(
     Parameters
     ----------
     requirement
-        A requirement object
+        A requirement object.
     pin_exact
         If True, pin requirement to version rather than using existing
         specifier. Allows you to convert minimum versions to pinned versions.
@@ -49,6 +49,7 @@ def make_requirement(
     Returns
     -------
     requirement_str
+        The requirement's name and its specifier(s).
     """
     specifiers = list(requirement.specifier)
     if pin_exact and len(specifiers) == 1:
diff --git a/osmnx/convert.py b/osmnx/convert.py
index 0d70e22e..08e7b2ed 100644
--- a/osmnx/convert.py
+++ b/osmnx/convert.py
@@ -223,7 +223,6 @@ def _validate_node_edge_gdfs(
         GeoDataFrame of graph nodes uniquely indexed by `osmid`.
     gdf_edges
         GeoDataFrame of graph edges uniquely multi-indexed by `(u, v, key)`.
-    graph_attrs
 
     Returns
     -------
diff --git a/osmnx/features.py b/osmnx/features.py
index 626ca08b..38c06923 100644
--- a/osmnx/features.py
+++ b/osmnx/features.py
@@ -351,10 +351,10 @@ def features_from_xml(
     ----------
     filepath
         Path to file containing OSM XML data.
-    tags
-        Query tags to optionally filter the final GeoDataFrame.
     polygon
         Spatial boundaries to optionally filter the final GeoDataFrame.
+    tags
+        Query tags to optionally filter the final GeoDataFrame.
     encoding
         The OSM XML file's character encoding.
 
diff --git a/osmnx/graph.py b/osmnx/graph.py
index 7a9efaee..ea0d920e 100644
--- a/osmnx/graph.py
+++ b/osmnx/graph.py
@@ -599,9 +599,6 @@ def _create_graph(
     ----------
     response_jsons
         Iterable of JSON responses from the Overpass API.
-    retain_all
-        If True, return the entire graph even if it is not connected.
-        Otherwise, retain only the largest weakly connected component.
     bidirectional
         If True, create bidirectional edges for one-way streets.
 
diff --git a/osmnx/plot.py b/osmnx/plot.py
index 9056296a..ccc4a7ee 100644
--- a/osmnx/plot.py
+++ b/osmnx/plot.py
@@ -325,7 +325,7 @@ def plot_graph_route(
         Size of the origin and destination nodes.
     ax
         If not None, plot on this pre-existing axes instance.
-    pg_kwargs
+    **pg_kwargs
         Keyword arguments to pass to `plot_graph`.
 
     Returns
@@ -394,7 +394,7 @@ def plot_graph_routes(
     route_linewidths
         If float, the one linewidth for all routes. Otherwise, the linewidth
         for each route.
-    pgr_kwargs
+    **pgr_kwargs
         Keyword arguments to pass to `plot_graph_route`.
 
     Returns
@@ -487,7 +487,7 @@ def plot_figure_ground(
         Fallback width, in pixels, for any street type not in `street_widths`.
     color
         The color of the streets.
-    pg_kwargs
+    **pg_kwargs
         Keyword arguments to pass to `plot_graph`.
 
     Returns
diff --git a/osmnx/projection.py b/osmnx/projection.py
index 2e946bd0..4d143c5f 100644
--- a/osmnx/projection.py
+++ b/osmnx/projection.py
@@ -31,7 +31,7 @@ def is_projected(crs: Any) -> bool:  # noqa: ANN401
     Returns
     -------
     projected
-        True if `crs` is projected, otherwise False
+        True if `crs` is projected, otherwise False.
     """
     return bool(gpd.GeoSeries(crs=crs).crs.is_projected)
 
diff --git a/osmnx/routing.py b/osmnx/routing.py
index 013e17b1..7643aecc 100644
--- a/osmnx/routing.py
+++ b/osmnx/routing.py
@@ -316,7 +316,7 @@ def shortest_path(
     Parameters
     ----------
     G
-        Input graph,
+        Input graph.
     orig
         Origin node ID(s).
     dest
diff --git a/pyproject.toml b/pyproject.toml
index 92742ae2..909c7905 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -69,6 +69,9 @@ strict = true
 warn_no_return = true
 warn_unreachable = true
 
+[tool.numpydoc_validation]
+checks = ["all", "ES01", "EX01", "GL08", "PR04", "RT03", "SA01"]
+
 [tool.ruff]
 cache-dir = "~/.cache/pre-commit/ruff"
 exclude = ["build/*"]