initial pass at docs

.gitignore

@@ -169,4 +169,5 @@ cache/
 .pixi
 *.egg-info
 
-ci_artifacts/
+ci_artifacts/
+docs/source/generated

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_static/custom.css

@@ -0,0 +1,3 @@
+.logo-frontpage {
+    margin-bottom: 30px;
+}

docs/source/_static/references.bib

@@ -0,0 +1,14 @@
+@article{fleischmann_shape-based_2024,
+  title = {A Shape-Based Heuristic for the Detection of Urban Block Artifacts in Street Networks},
+  author = {Fleischmann, Martin and Vybornova, Anastassia},
+  year = {2024},
+  month = jun,
+  journal = {Journal of Spatial Information Science},
+  volume = {28},
+  pages = {75--102},
+  doi = {10.5311/JOSIS.2024.28.319},
+  urldate = {2024-06-27},
+  abstract = {Street networks are ubiquitous components of cities, guiding their development and enabling movement from place to place; street networks are also the critical components of many urban analytical methods. However, their graph representation is often designed primarily for transportation purposes. This representation is less suitable for other use cases where transportation networks need to be simplified as a mandatory pre-processing step, e.g., in the case of morphological analysis, visual navigation, or drone flight routing. While the urgent demand for automated pre-processing methods comes from various fields, it is still an unsolved challenge. In this article, we tackle this challenge by proposing a cheap computational heuristic for the identification of ``face artifacts'', i.e., geometries that are enclosed by transportation edges but do not represent urban blocks. The heuristic is based on combining the frequency distributions of shape compactness metrics and area measurements of street network face polygons. We test our method on 131 globally sampled large cities and show that it successfully identifies face artifacts in 89{\textbackslash}\% of analyzed cities. Our heuristic of detecting artifacts caused by data being collected for another purpose is the first step towards an automated street network simplification workflow. Moreover, the proposed face artifact index uncovers differences in structural rules guiding the development of cities in different world regions.},
+  copyright = {Creative Commons Attribution-NoDerivatives 4.0 International Licence (CC-BY-ND)},
+  langid = {english}
+}

docs/source/api.rst

@@ -0,0 +1,57 @@
+.. _reference:
+
+.. currentmodule:: neatnet
+
+API reference
+=============
+
+The API reference provides an overview of all public functions in ``neatnet``.
+
+Network Simplification Routines
+-------------------------------
+
+The top-level function that performs complete adaptive simplification of street networks
+is the primary API of ``neatnet``.
+
+.. autosummary::
+   :toctree: generated/
+
+   simplify_network
+
+Simplification Components
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some of the individual components are also exposed as independent functions (note that
+all are consumed by :func:`simplify_network`).
+
+Either as combined routines:
+
+.. autosummary::
+   :toctree: generated/
+
+   consolidate_nodes
+   fix_topology
+
+Or as their atomic components:
+
+.. autosummary::
+   :toctree: generated/
+
+   remove_false_nodes
+   induce_nodes
+
+Internal components
+-------------------
+
+For debugging purposes, users may use some parts of the internal API.
+
+.. autosummary::
+   :toctree: generated/
+
+   get_artifacts
+   simplify_loop
+   simplify_singletons
+   simplify_pairs
+   simplify_clusters
+
+None of the other functions is intended for public use and their API can change without a warning.

docs/source/conf.py

@@ -0,0 +1,90 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+
+import sphinx_autosummary_accessors
+
+sys.path.insert(0, os.path.abspath("../neatnet/"))
+
+import neatnet  # noqa
+
+project = "NeatNet"
+copyright = "2024-, neatnet Developers"
+author = "Martin Fleischmann, Anastassia Vybornova, James D. Gaboardi"
+
+version = neatnet.__version__
+release = neatnet.__version__
+
+language = "en"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "numpydoc",
+    "myst_nb",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.mathjax",
+    "sphinxcontrib.bibtex",
+    "sphinx_autosummary_accessors",
+    "sphinx_copybutton",
+]
+
+bibtex_bibfiles = ["_static/references.bib"]
+
+master_doc = "index"
+
+templates_path = [
+    "_templates",
+    sphinx_autosummary_accessors.templates_path,
+]
+exclude_patterns = []
+
+intersphinx_mapping = {
+    "esda": (
+        "https://pysal.org/esda/",
+        "https://pysal.org/esda//objects.inv",
+    ),
+    "geopandas": ("https://geopandas.org/en/latest", None),
+    "libpysal": (
+        "https://pysal.org/libpysal/",
+        "https://pysal.org/libpysal//objects.inv",
+    ),
+    "momepy": ("http://docs.momepy.org/en/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs", None),
+    "pyproj": ("https://pyproj4.github.io/pyproj/latest/", None),
+    "python": ("https://docs.python.org/3", None),
+    "shapely": ("https://shapely.readthedocs.io/en/latest/", None),
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+autosummary_generate = True
+numpydoc_show_class_members = False
+numpydoc_use_plots = True
+class_members_toctree = True
+numpydoc_show_inherited_class_members = True
+numpydoc_xref_param_type = True
+autodoc_default_options = {"members": True, "undoc-members": True}
+plot_include_source = True
+
+html_theme = "sphinx_book_theme"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_logo = "_static/logo.svg"
+html_favicon = "_static/icon.png"
+html_theme_options = {
+    "use_sidenotes": True,
+}
+nb_execution_mode = "off"
+autodoc_typehints = "none"