Merge pull request #1185 from gboeing/docs

update documentation

.pre-commit-config.yaml

@@ -29,13 +29,13 @@ repos:
         types_or: [markdown, yaml]
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: "v0.40.0"
+    rev: "v0.41.0"
     hooks:
       - id: markdownlint
         args: [--disable=MD013]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.4.2"
+    rev: "v0.4.10"
     hooks:
       - id: ruff
         args: [--fix]

docs/source/getting-started.rst

@@ -70,15 +70,6 @@ In short, MultiDiGraphs are nonplanar directed graphs with possible self-loops a
 
 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.
 
-Model Attributes
-^^^^^^^^^^^^^^^^
-
-An OSMnx model has some standard required attributes, plus some optional attributes. The latter are sometimes present based on the source OSM data's tagging, the :code:`settings` module configuration, and any processing you may have done to add additional attributes (as noted in various functions' documentation).
-
-As a NetworkX MultiDiGraph object, it has top-level :code:`graph`, :code:`nodes`, and :code:`edges` attributes. The :code:`graph` attribute dictionary must contain a "crs" key defining its coordinate reference system. The :code:`nodes` are identified by OSM ID and each must contain a :code:`data` attribute dictionary that must have "x" and "y" keys defining its coordinates and a "street_count" key defining how many physical streets are incident to it. The :code:`edges` are identified by a 3-tuple of "u" (source node ID), "v" (target node ID), and "key" (to differentiate parallel edges), and each must contain a :code:`data` attribute dictionary that must have an "osmid" key defining its OSM ID and a "length" key defining its length in meters.
-
-The OSMnx :code:`graph` module automatically creates MultiDiGraphs with these required attributes, plus additional optional attributes based on the :code:`settings` module configuration. If you instead manually create your own graph model, make sure it has these required attributes at a minimum.
-
 Topology Clean-Up
 ^^^^^^^^^^^^^^^^^
 
@@ -88,19 +79,23 @@ 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.
 
-Converting, Projecting, Saving
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Model Attributes
+^^^^^^^^^^^^^^^^
 
-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.
+An OSMnx model has some standard required attributes, plus some optional attributes. The latter are sometimes present based on the source OSM data's tagging, the :code:`settings` module configuration, and any processing you may have done to add additional attributes (as noted in various functions' documentation).
 
-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.
+As a NetworkX `MultiDiGraph`_ object, it has top-level :code:`graph`, :code:`nodes`, and :code:`edges` attributes. The :code:`graph` attribute dictionary must contain a "crs" key defining its coordinate reference system. The :code:`nodes` are identified by OSM ID and each must contain a :code:`data` attribute dictionary that must have "x" and "y" keys defining its coordinates and a "street_count" key defining how many physical streets are incident to it. The :code:`edges` are identified by a 3-tuple of "u" (source node ID), "v" (target node ID), and "key" (to differentiate parallel edges), and each must contain a :code:`data` attribute dictionary that must have an "osmid" key defining its OSM ID and a "length" key defining its length in meters.
 
-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.
+The OSMnx :code:`graph` module automatically creates MultiDiGraphs with these required attributes, plus additional optional attributes based on the :code:`settings` module configuration. If you instead manually create your own graph model, make sure it has these required attributes at a minimum.
 
-Working with Elevation
+Convert, Project, Save
 ^^^^^^^^^^^^^^^^^^^^^^
 
-The :code:`elevation` module lets you automatically attach elevations to the graph's nodes from a local raster file or a web service like the Google Maps `Elevation API`_. You can also calculate edge grades (i.e., rise-over-run) and analyze the steepness of certain streets or routes.
+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.
+
+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.
+
+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.
 
 Network Measures
 ^^^^^^^^^^^^^^^^
@@ -109,6 +104,11 @@ You can use the :code:`stats` module to calculate a variety of geometric and top
 
 You can also use NetworkX directly to calculate additional topological network measures.
 
+Working with Elevation
+^^^^^^^^^^^^^^^^^^^^^^
+
+The :code:`elevation` module lets you automatically attach elevations to the graph's nodes from a local raster file or a web service like the Google Maps `Elevation API`_. You can also calculate edge grades (i.e., rise-over-run) and analyze the steepness of certain streets or routes.
+
 Routing
 ^^^^^^^
 
@@ -119,7 +119,6 @@ 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.
 
-
 Usage Limits
 ^^^^^^^^^^^^
 
@@ -143,25 +142,27 @@ Frequently Asked Questions
 
 *I have a usage question.* Please ask it on `StackOverflow`_.
 
+
+.. _Changelog: https://github.com/gboeing/osmnx/blob/main/CHANGELOG.md
+.. _CRS: https://en.wikipedia.org/wiki/Coordinate_reference_system
+.. _DiGraph: https://networkx.org/documentation/stable/reference/classes/digraph.html
+.. _elements: https://wiki.openstreetmap.org/wiki/Elements
+.. _Elevation API: https://developers.google.com/maps/documentation/elevation
 .. _Examples Gallery: https://github.com/gboeing/osmnx-examples
+.. _features: https://wiki.openstreetmap.org/wiki/Map_features
+.. _Folium: https://python-visualization.github.io/folium/
+.. _GeoDataFrames: https://geopandas.org/en/stable/docs/reference/geodataframe.html
 .. _GeoPandas: https://geopandas.org
+.. _MultiDiGraph: https://networkx.org/documentation/stable/reference/classes/multidigraph.html
+.. _MultiDiGraphs: https://networkx.org/documentation/stable/reference/classes/multidigraph.html
+.. _MultiGraph: https://networkx.org/documentation/stable/reference/classes/multigraph.html
 .. _NetworkX: https://networkx.org
-.. _OpenStreetMap: https://www.openstreetmap.org
 .. _Nominatim: https://nominatim.org
+.. _Nominatim Usage Policy: https://operations.osmfoundation.org/policies/nominatim/
+.. _OpenStreetMap: https://www.openstreetmap.org
 .. _Overpass: https://wiki.openstreetmap.org/wiki/Overpass_API
-.. _features: https://wiki.openstreetmap.org/wiki/Map_features
-.. _tags: https://wiki.openstreetmap.org/wiki/Tags
-.. _elements: https://wiki.openstreetmap.org/wiki/Elements
-.. _MultiDiGraphs: https://networkx.org/documentation/stable/reference/classes/multidigraph.html
-.. _MultiGraph: https://networkx.org/documentation/stable/reference/classes/multigraph.html
-.. _DiGraph: https://networkx.org/documentation/stable/reference/classes/digraph.html
-.. _GeoDataFrames: https://geopandas.org/en/stable/docs/reference/geodataframe.html
+.. _Overpass Commons: https://dev.overpass-api.de/overpass-doc/en/preface/commons.html
 .. _Overpass QL: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL
-.. _CRS: https://en.wikipedia.org/wiki/Coordinate_reference_system
-.. _Elevation API: https://developers.google.com/maps/documentation/elevation
-.. _Folium: https://python-visualization.github.io/folium/
-.. _Changelog: https://github.com/gboeing/osmnx/blob/main/CHANGELOG.md
 .. _projects: https://geoffboeing.com/2018/03/osmnx-features-roundup
 .. _StackOverflow: https://stackoverflow.com/search?q=osmnx
-.. _Nominatim Usage Policy: https://operations.osmfoundation.org/policies/nominatim/
-.. _Overpass Commons: https://dev.overpass-api.de/overpass-doc/en/preface/commons.html
+.. _tags: https://wiki.openstreetmap.org/wiki/Tags

docs/source/index.rst

@@ -55,12 +55,12 @@ Documentation
 .. toctree::
    :maxdepth: 1
 
-   getting-started
+   installation
 
 .. toctree::
    :maxdepth: 1
 
-   installation
+   getting-started
 
 .. toctree::
    :maxdepth: 1

docs/source/installation.rst

@@ -22,7 +22,7 @@ You can run OSMnx + JupyterLab directly from the official OSMnx `Docker`_ image.
 Pip
 ---
 
-You may be able to install OSMnx with `pip`_ (in a virtual environment) but this is not officially supported. OSMnx is written in pure Python and its installation alone is thus trivially simple if you already have its dependencies installed and tested on your system. OSMnx depends on packages that in turn depend on C/C++ libraries, and installing those dependencies with pip is sometimes challenging depending on your specific system's configuration. If you're not sure what you're doing, just follow the conda instructions above to avoid installation problems.
+You may be able to install OSMnx with `pip`_ (into a virtual environment) but this is not officially supported. OSMnx is written in pure Python and its installation alone is thus trivially simple if you already have its dependencies installed and tested on your system. OSMnx depends on packages that in turn depend on C/C++ libraries, and installing those dependencies with pip is sometimes challenging depending on your specific system's configuration. If you're not sure what you're doing, just follow the conda instructions above to avoid installation problems.
 
 .. _conda: https://conda.io/
 .. _conda-forge: https://conda-forge.org/

osmnx/_version.py

@@ -1,3 +1,3 @@
 """OSMnx package version information."""
 
-__version__ = "2.0.0b0"
+__version__ = "2.0.0b1"