DOC: rework API docs around the new functional stuff (#597)

.gitignore

@@ -66,6 +66,7 @@ instance/
 # Sphinx documentation
 docs/_build/
 docs/generated/
+docs/api/
 
 # PyBuilder
 target/

docs/_static/references.bib

@@ -209,7 +209,6 @@ @article{tripathy2020open
   title     = {An open-source tool to extract natural continuity and hierarchy of urban street networks},
   author    = {Tripathy, Pratyush and Rao, Pooja and Balakrishnan, Krishnachandran and Malladi, Teja},
   journal   = {Environment and Planning B: Urban Analytics and City Science},
-  pages     = {2399808320967680},
   year      = {2020},
   publisher = {SAGE Publications Sage UK: London, England},
   volume    = {48},

docs/api.rst

@@ -4,101 +4,152 @@
 
 .. currentmodule:: momepy
 
-
 momepy API reference
 ======================
 
-elements
---------
+The current version of momepy includes two implementations of most of the functionality
+due to the ongoing migration period moving from the legacy class-based API to a new
+function-based API. This page outlines the stable API. For the legacy functionality, see
+:doc:`Legacy API  <legacy_api>`.
+
+Managing morphological elements
+-------------------------------
+.. _elements:
+
+Momepy allows creation of a small subset of bespoke morphological geometric features.
 
 .. autosummary::
-   :toctree: generated/
+   :toctree: api/
 
-   Blocks
-   buffered_limit
-   COINS
+   morphological_tessellation
+   enclosed_tessellation
    enclosures
-   get_network_id
+   generate_blocks
+
+Additionally, it contains tools supporting these.
+
+.. autosummary::
+   :toctree: api/
+
+   buffered_limit
+   verify_tessellation
+
+And tools linking various elements together.
+
+.. autosummary::
+   :toctree: api/
+
+   get_nearest_street
    get_network_ratio
    get_node_id
-   Tessellation
 
-dimension
----------
+Measuring dimension
+-------------------
+
+A set of functions to measure dimensions of geometric elements:
 
 .. autosummary::
-   :toctree: generated/
-
-   Area
-   AverageCharacter
-   CourtyardArea
-   CoveredArea
-   FloorArea
-   LongestAxisLength
-   Perimeter
-   PerimeterWall
-   SegmentsLength
-   StreetProfile
-   Volume
-   WeightedCharacter
-
-shape
------
+   :toctree: api/
+
+   courtyard_area
+   floor_area
+   longest_axis_length
+   perimeter_wall
+   street_profile
+   volume
+   weighted_character
+
+Measuring shape
+---------------
+
+A set of functions to measure shape of geometric elements:
 
 .. autosummary::
-  :toctree: generated/
-
-  CentroidCorners
-  CircularCompactness
-  CompactnessWeightedAxis
-  Convexity
-  Corners
-  CourtyardIndex
-  Elongation
-  EquivalentRectangularIndex
-  FormFactor
-  FractalDimension
-  Linearity
-  Rectangularity
-  ShapeIndex
-  SquareCompactness
-  Squareness
-  VolumeFacadeRatio
-
-spatial distribution
---------------------
+   :toctree: api/
+
+   centroid_corner_distance
+   circular_compactness
+   compactness_weighted_axis
+   convexity
+   corners
+   courtyard_index
+   elongation
+   equivalent_rectangular_index
+   facade_ratio
+   form_factor
+   fractal_dimension
+   linearity
+   rectangularity
+   shape_index
+   square_compactness
+   squareness
+
+Measuring spatial distribution
+------------------------------
+
+A set of functions to measure spatial distribution of geometric elements:
+
 .. autosummary::
-  :toctree: generated/
-
-  Alignment
-  BuildingAdjacency
-  CellAlignment
-  MeanInterbuildingDistance
-  NeighborDistance
-  NeighboringStreetOrientationDeviation
-  Neighbors
-  Orientation
-  SharedWalls
-  SharedWallsRatio
-  StreetAlignment
-
-intensity
----------
+   :toctree: api/
+
+   alignment
+   building_adjacency
+   cell_alignment
+   mean_interbuilding_distance
+   neighbor_distance
+   neighbors
+   orientation
+   shared_walls
+   street_alignment
+
+Measuring intensity
+-------------------
+
+A set of functions to measure intensity characters:
+
 .. autosummary::
-   :toctree: generated/
-
-   AreaRatio
-   BlocksCount
-   Count
-   Courtyards
-   Density
-   NodeDensity
-   Reached
-
-graph
-------------
+   :toctree: api/
+
+   courtyards
+   node_density
+
+Note that additional intensity characters can be directly derived using :meth:`libpysal.graph.Graph.describe`
+and functions :func:`describe_agg` and :func:`describe_reached_agg` belonging to the diversity module.
+
+Measuring diversity
+-------------------
+
+A set of functions to measure spatial diversity of elements and their values:
+
 .. autosummary::
-   :toctree: generated/
+   :toctree: api/
+
+   describe_agg
+   describe_reached_agg
+   gini
+   percentile
+   shannon
+   simpson
+   theil
+   values_range
+
+
+Underlying components of :func:`shannon` and :func:`simpson` are also exposed for direct use:
+
+
+.. autosummary::
+   :toctree: api/
+
+   shannon_diversity
+   simpson_diversity
+
+Measuring connectivity
+----------------------
+
+A set of functions for the analysis of connectivity and configuration of street networks:
+
+.. autosummary::
+   :toctree: api/
 
    betweenness_centrality
    cds_length
@@ -115,52 +166,44 @@ graph
    proportion
    straightness_centrality
    subgraph
+   COINS
 
-diversity
----------
-.. autosummary::
-   :toctree: generated/
+With utilities allowing conversion between networkx objects and GeoPandas objects.
 
-   Gini
-   Percentiles
-   Range
-   Shannon
-   Simpson
-   Theil
-   Unique
+.. autosummary::
+   :toctree: api/
 
-   shannon_diversity
-   simpson_diversity
+   gdf_to_nx
+   nx_to_gdf
 
-spatial weights
----------------
-.. autosummary::
-   :toctree: generated/
+Data preprocessing
+------------------
 
-   DistanceBand
-   sw_high
+Most of the algorithms have certain expectations about the quality of input data. The
+`preprocessing` module helps adapting the input data and fixing common issues.
 
-preprocessing
--------------
 .. autosummary::
-   :toctree: generated/
+   :toctree: api/
 
    close_gaps
-   consolidate_intersections
-   CheckTessellationInput
    extend_lines
-   FaceArtifacts
    remove_false_nodes
-   preprocess
+   consolidate_intersections
    roundabout_simplification
 
+Additionally, there are methods for data assessment.
 
-utilities
----------
 .. autosummary::
-   :toctree: generated/
+   :toctree: api/
 
-   gdf_to_nx
-   limit_range
-   nx_to_gdf
-   unique_id
+   CheckTessellationInput
+   FaceArtifacts
+
+
+Further analysis can be done directly using methods available in :class:`libpysal.graph.Graph`.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   legacy_api

docs/conf.py

@@ -16,7 +16,7 @@
 
 # import sphinx_bootstrap_theme
 
-sys.path.insert(0, os.path.abspath("../.."))
+sys.path.insert(0, os.path.abspath("../"))
 
 import momepy  # noqa
 
@@ -129,7 +129,6 @@
 html_theme_options = {
     "github_url": "https://github.com/pysal/momepy",
     "twitter_url": "https://twitter.com/martinfleis",
-    "google_analytics_id": "UA-6190355-13",
     "pygment_light_style": "tango",
     "logo": {
         "image_light": "horizontal_logo_light.svg",
@@ -246,13 +245,23 @@ def setup(app):
 }
 
 # -- Extension configuration -------------------------------------------------
+intersphinx_mapping = {
+    "libpysal": (
+        "https://pysal.org/libpysal/",
+        "https://pysal.org/libpysal//objects.inv",
+    ),
+}
+
+
 # Generate the API documentation when building
 autosummary_generate = True
 autosummary_imported_members = True
 numpydoc_show_class_members = True
 class_members_toctree = True
 numpydoc_show_inherited_class_members = True
+numpydoc_class_members_toctree = False
 numpydoc_use_plots = True
+autodoc_typehints = "none"
 
 nbsphinx_prolog = r"""
 {% set docname = env.doc2path(env.docname, base=None) %}