Merge pull request #1259 from gboeing/docs

Improve documentation

docs/source/getting-started.rst

@@ -6,7 +6,7 @@ Get Started in 4 Steps
 
 1. Install OSMnx by following the :doc:`installation` guide.
 
-2. Read ":ref:`introducing-osmnx`" below on this page.
+2. Read the :ref:`introducing-osmnx` section on this page.
 
 3. Work through the OSMnx `Examples Gallery`_ for step-by-step tutorials and sample code.
 
@@ -54,7 +54,7 @@ Read more about the :ref:`settings <osmnx-settings-module>` module in the User R
 Geocoding and Querying
 ^^^^^^^^^^^^^^^^^^^^^^
 
-OSMnx geocodes place names and addresses with the OpenStreetMap `Nominatim`_ API. You can use the :code:`geocoder` module to geocode place names or addresses to lat-lon coordinates. Or, you can retrieve place boundaries or any other OpenStreetMap elements by name or ID.
+OSMnx geocodes place names and addresses with the OpenStreetMap `Nominatim`_ API. You can use the :code:`geocoder` module to geocode place names or addresses to lat-lon coordinates. Or, you can retrieve place boundaries or any other OpenStreetMap elements by name or ID. Read more about the :ref:`geocoder <osmnx-geocoder-module>` module in the User Reference.
 
 Using the :code:`features` and :code:`graph` modules, as described below, you can download data by lat-lon point, address, bounding box, bounding polygon, or place name (e.g., neighborhood, city, county, etc).
 
@@ -63,14 +63,18 @@ Urban Amenities
 
 Using OSMnx's :code:`features` module, you can search for and download any geospatial `features`_ (such as building footprints, grocery stores, schools, public parks, transit stops, etc) from the OpenStreetMap `Overpass`_ API as a GeoPandas GeoDataFrame. This uses OpenStreetMap `tags`_ to search for matching `elements`_.
 
+Read more about the :ref:`features <osmnx-features-module>` module in the User Reference.
+
 Modeling a Network
 ^^^^^^^^^^^^^^^^^^
 
-Using OSMnx's :code:`graph` module, you can retrieve any spatial network data (such as streets, paths, rail, canals, etc) from the Overpass API and model them as NetworkX `MultiDiGraphs`_. See the official reference paper at the :doc:`further-reading` page for complete modeling details.
+Using OSMnx's :code:`graph` module, you can retrieve any spatial network data (such as streets, paths, rail, canals, etc) from the Overpass API and model them as NetworkX `MultiDiGraphs`_.
 
 In short, MultiDiGraphs are nonplanar directed graphs with possible self-loops and parallel edges. Thus, a one-way street will be represented with a single directed edge from node *u* to node *v*, but a bidirectional street will be represented with two reciprocal directed edges (with identical geometries): one from node *u* to node *v* and another from *v* to *u*, to represent both possible directions of flow. Because these graphs are nonplanar, they correctly model the topology of interchanges, bridges, and tunnels. That is, edge crossings in a two-dimensional plane are not intersections in an OSMnx model unless they represent true junctions in the three-dimensional real world.
 
-The :code:`graph` module uses filters to query the Overpass API: you can either specify a built-in network type or provide your own custom filter with `Overpass QL`_. Refer to the :code:`graph` module's documentation for more details. Under the hood, OSMnx does several things to generate the best possible model. It initially creates a 500m-buffered graph before truncating it to your desired query area, to ensure accurate streets-per-node stats and to attenuate graph perimeter effects. It also simplifies the graph topology as discussed below.
+The :code:`graph` module uses filters to query the Overpass API: you can either specify a built-in network type or provide your own custom filter with `Overpass QL`_. Under the hood, OSMnx does several things to generate the best possible model. It initially creates a 500m-buffered graph before truncating it to your desired query area, to ensure accurate streets-per-node stats and to attenuate graph perimeter effects. By default, it returns the largest weakly connected component. It also simplifies the graph topology as discussed below.
+
+Read more about the :ref:`graph <osmnx-graph-module>` module in the User Reference and refer to the official reference paper at the :doc:`further-reading` page for complete modeling details.
 
 Topology Clean-Up
 ^^^^^^^^^^^^^^^^^
@@ -81,6 +85,8 @@ The :code:`simplification` module automatically processes the network's topology
 
 **Intersection consolidation** is important because many real-world street networks feature complex intersections and traffic circles, resulting in a cluster of graph nodes where there is really just one true intersection as we would think of it in transportation or urban design. Similarly, divided roads are often represented by separate centerline edges: the intersection of two divided roads thus creates 4 nodes, representing where each edge intersects a perpendicular edge, but these 4 nodes represent a single intersection in the real world. OSMnx can consolidate such complex intersections into a single node and optionally rebuild the graph's edge topology accordingly. When multiple OpenStreetMap nodes are merged into a single graph node, the nodes' attribute values can be aggregated into a single value.
 
+Read more about the :ref:`simplification <osmnx-simplification-module>` module in the User Reference.
+
 Model Attributes
 ^^^^^^^^^^^^^^^^
 
@@ -93,16 +99,18 @@ The OSMnx :code:`graph` module automatically creates MultiDiGraphs with these re
 Convert, Project, Save
 ^^^^^^^^^^^^^^^^^^^^^^
 
-OSMnx's :code:`convert` module can convert a MultiDiGraph to a `MultiGraph`_ if you prefer an undirected representation of the network, or to a `DiGraph`_ if you prefer a directed representation without any parallel edges. It can also convert a MultiDiGraph to/from GeoPandas node and edge `GeoDataFrames`_. The nodes GeoDataFrame is indexed by OSM ID and the edges GeoDataFrame is multi-indexed by :code:`u, v, key` just like a NetworkX edge. This allows you to load arbitrary node/edge ShapeFiles or GeoPackage layers as GeoDataFrames then model them as a MultiDiGraph for graph analysis.
+OSMnx's :code:`convert` module can convert a MultiDiGraph to a `DiGraph`_ if you prefer a directed representation of the network without any parallel edges, or to a `MultiGraph`_ if you need an undirected representation for use with functions or algorithms that only accept a MultiGraph object. If you just want a fully bidirectional graph (such as for a walking network), just configure the `settings` module's `bidirectional_network_types` before creating your graph.
+
+The :code:`convert` module can also convert a MultiDiGraph to/from GeoPandas node and edge `GeoDataFrames`_. The nodes GeoDataFrame is indexed by OSM ID and the edges GeoDataFrame is multi-indexed by :code:`u, v, key` just like a NetworkX edge. This allows you to load arbitrary node/edge ShapeFiles or GeoPackage layers as GeoDataFrames then model them as a MultiDiGraph for graph analysis. Read more about the :ref:`convert <osmnx-convert-module>` module in the User Reference.
 
-You can easily project your graph to different coordinate reference systems using the :code:`projection` module. If you're unsure which `CRS`_ you want to project to, OSMnx can automatically determine an appropriate UTM CRS for you.
+You can easily project your graph to different coordinate reference systems using the :code:`projection` module. If you're unsure which `CRS`_ you want to project to, OSMnx can automatically determine an appropriate UTM CRS for you. Read more about the :ref:`projection <osmnx-projection-module>` module in the User Reference.
 
-Using the :code:`io` module, you can save your graph to disk as a GraphML file (to load into other network analysis software), a GeoPackage (to load into other GIS software), or an OSM XML file. Use the GraphML format whenever saving a graph for later work with OSMnx.
+Using the :code:`io` module, you can save your graph to disk as a GraphML file (to load into other network analysis software), a GeoPackage (to load into other GIS software), or an OSM XML file. Use the GraphML format whenever saving a graph for later work with OSMnx. Read more about the :ref:`io <osmnx-io-module>` module in the User Reference.
 
 Network Measures
 ^^^^^^^^^^^^^^^^
 
-You can use the :code:`stats` module to calculate a variety of geometric and topological measures as well as street network bearing and orientation statistics. These measures define streets as the edges in an undirected representation of the graph to prevent double-counting bidirectional edges of a two-way street. You can easily generate common stats in transportation studies, urban design, and network science, including intersection density, circuity, average node degree (connectedness), betweenness centrality, and much more.
+You can use the :code:`stats` module to calculate a variety of geometric and topological measures as well as street network bearing and orientation statistics. These measures define streets as the edges in an undirected representation of the graph to prevent double-counting bidirectional edges of a two-way street. You can easily generate common stats in transportation studies, urban design, and network science, including intersection density, circuity, average node degree (connectedness), betweenness centrality, and much more. Read more about the :ref:`stats <osmnx-stats-module>` module in the User Reference.
 
 You can also use NetworkX directly to calculate additional topological network measures.
 
@@ -111,16 +119,22 @@ Working with Elevation
 
 The :code:`elevation` module lets you automatically attach elevations to the graph's nodes from a local raster file or the Google Maps `Elevation API`_ (or equivalent web API with a compatible interface). You can also calculate edge grades (i.e., rise-over-run) and analyze the steepness of certain streets or routes.
 
+Read more about the :ref:`elevation <osmnx-elevation-module>` module in the User Reference.
+
 Routing
 ^^^^^^^
 
 The :code:`distance` module can find the nearest node(s) or edge(s) to coordinates using a fast spatial index. The :code:`routing` module can solve shortest paths for network routing, parallelized with multiprocessing, using different weights (e.g., distance, travel time, elevation change, etc). It can also impute missing speeds to the graph edges. This imputation can obviously be imprecise, so the user can override it by passing in arguments that define local speed limits. It can also calculate free-flow travel times for each edge.
 
+Read more about the :ref:`distance <osmnx-distance-module>` and :ref:`routing <osmnx-routing-module>` modules in the User Reference.
+
 Visualization
 ^^^^^^^^^^^^^
 
 You can plot graphs, routes, network figure-ground diagrams, building footprints, and street network orientation rose diagrams (aka, polar histograms) with the :code:`plot` module. You can also explore street networks, routes, or geospatial features as interactive `Folium`_ web maps.
 
+Read more about the :ref:`plot <osmnx-plot-module>` module in the User Reference.
+
 Usage Limits
 ^^^^^^^^^^^^
 
@@ -129,7 +143,7 @@ Refer to the `Nominatim Usage Policy`_ and `Overpass Commons`_ documentation for
 More Info
 ---------
 
-All of this functionality is demonstrated step-by-step in the OSMnx `Examples Gallery`_, and usage is detailed in the :doc:`user-reference`. More feature development details are in the `Changelog`_. Consult the :doc:`further-reading` resources for additional technical details and research.
+All of this functionality is demonstrated step-by-step in the OSMnx `Examples Gallery`_, and usage is detailed in the :doc:`user-reference`. Feature development details are in the `Changelog`_. Consult the :doc:`further-reading` resources for additional technical details and research.
 
 Frequently Asked Questions
 --------------------------

docs/source/user-reference.rst

@@ -7,66 +7,88 @@ OSMnx 2.0 is released: read the `migration guide`_.
 
 .. _migration guide: https://github.com/gboeing/osmnx/issues/1123
 
+.. _osmnx-bearing-module:
+
 osmnx.bearing module
 --------------------
 
 .. automodule:: osmnx.bearing
     :members:
 
+.. _osmnx-convert-module:
+
 osmnx.convert module
 --------------------
 
 .. automodule:: osmnx.convert
     :members:
 
+.. _osmnx-distance-module:
+
 osmnx.distance module
 ---------------------
 
 .. automodule:: osmnx.distance
     :members:
 
+.. _osmnx-elevation-module:
+
 osmnx.elevation module
 ----------------------
 
 .. automodule:: osmnx.elevation
     :members:
 
+.. _osmnx-features-module:
+
 osmnx.features module
 ---------------------
 
 .. automodule:: osmnx.features
     :members:
 
+.. _osmnx-geocoder-module:
+
 osmnx.geocoder module
 ---------------------
 
 .. automodule:: osmnx.geocoder
     :members:
 
+.. _osmnx-graph-module:
+
 osmnx.graph module
 ------------------
 
 .. automodule:: osmnx.graph
     :members:
 
+.. _osmnx-io-module:
+
 osmnx.io module
 ---------------
 
 .. automodule:: osmnx.io
     :members:
 
+.. _osmnx-plot-module:
+
 osmnx.plot module
 -----------------
 
 .. automodule:: osmnx.plot
     :members:
 
+.. _osmnx-projection-module:
+
 osmnx.projection module
 -----------------------
 
 .. automodule:: osmnx.projection
     :members:
 
+.. _osmnx-routing-module:
+
 osmnx.routing module
 -----------------------
 
@@ -81,30 +103,40 @@ osmnx.settings module
 .. automodule:: osmnx.settings
     :members:
 
+.. _osmnx-simplification-module:
+
 osmnx.simplification module
 ---------------------------
 
 .. automodule:: osmnx.simplification
     :members:
 
+.. _osmnx-stats-module:
+
 osmnx.stats module
 ------------------
 
 .. automodule:: osmnx.stats
     :members:
 
+.. _osmnx-truncate-module:
+
 osmnx.truncate module
 ---------------------
 
 .. automodule:: osmnx.truncate
     :members:
 
+.. _osmnx-utils-module:
+
 osmnx.utils module
 ------------------
 
 .. automodule:: osmnx.utils
     :members:
 
+.. _osmnx-utils_geo-module:
+
 osmnx.utils_geo module
 ----------------------
 

osmnx/convert.py

@@ -381,7 +381,7 @@ def to_undirected(G: nx.MultiDiGraph) -> nx.MultiGraph:
     Convert MultiDiGraph to undirected MultiGraph.
 
     This function has a limited use case: it allows you to create a MultiGraph
-    for use with functions/algorithms which only accept a MultiGraph object.
+    for use with functions/algorithms that only accept a MultiGraph object.
     Rather, if you want a fully bidirectional graph (such as for a walking
     network), configure the `settings` module's `bidirectional_network_types`
     before creating your graph to generate a fully bidirectional MultiDiGraph.