Add an about page and package documentation, linked from the homepage.

Author: njhenry

.github/workflows/deploy-site.yml

@@ -3,7 +3,7 @@ name: Deploy site to GitHub Pages
 on:
   push:
     branches: [main]
-    paths: ['site/**']
+    paths: ['site/**', 'src/**', 'docs/**']
   workflow_dispatch:
 
 permissions:
@@ -43,6 +43,23 @@ jobs:
         env:
           VITE_STADIA_API_KEY: ${{ secrets.VITE_STADIA_API_KEY }}
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Python dependencies
+        run: pip install -r docs/requirements.txt pandas
+
+      - name: Build taxonomy page
+        run: python scripts/build_taxonomy.py
+
+      - name: Build Sphinx docs
+        run: make html
+        working-directory: docs
+
+      - name: Copy Sphinx docs into site dist
+        run: cp -r docs/_build/html site/dist/docs
+
       - uses: actions/upload-pages-artifact@v3
         with:
           path: site/dist

Makefile

@@ -28,9 +28,27 @@ site_build:
 	@cd site && npm run build;
 
 # Serve the site locally with hot reload
+# Note: does not build Sphinx docs; use site_preview for a full build
 site_dev:
 	@cd site && npm run dev;
 
+# Generate site/public/taxonomy.html from the conflation data CSVs
+# Requires the openpois conda env to be active (for pandas)
+build_taxonomy:
+	@python scripts/build_taxonomy.py;
+
+# Full build + local preview: Sphinx docs, Vite production build, then serve
+# Mirrors the GitHub Actions workflow; serves at http://localhost:4173
+# Requires the openpois conda env to be active (for sphinx-build)
+# Uses Python's HTTP server instead of vite preview so /docs/ is served
+# correctly (vite preview uses SPA fallback which swallows directory requests)
+site_preview:
+	@python scripts/build_taxonomy.py
+	@sphinx-build -b html docs docs/_build/html -q
+	@cd site && npm run build
+	@cp -r docs/_build/html site/dist/docs
+	@python -m http.server 4173 --directory site/dist;
+
 # Convenience target to print all of the available targets in this file
 # From https://stackoverflow.com/questions/4219255
 .PHONY: list

docs/api.rst

@@ -0,0 +1,89 @@
+API Reference
+=============
+
+conflation
+----------
+
+.. automodule:: openpois.conflation.match
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.conflation.merge
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.conflation.taxonomy
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+io
+--
+
+.. automodule:: openpois.io.osm_snapshot
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.io.osm_history
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.io.overture
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.io.foursquare
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.io.s3
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.io.geohash_partition
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+models
+------
+
+.. automodule:: openpois.models.event_rate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.models.model_fitter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.models.setup
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.models.apply
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+osm
+---
+
+.. automodule:: openpois.osm.format_observations
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: openpois.osm.change_plots
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -1,67 +1,66 @@
 # Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import os
 import sys
 
 sys.path.insert(0, os.path.abspath("../src/"))
 
+# -- Project information -------------------------------------------------------
 
-# -- Project information -----------------------------------------------------
-
-project = "ai-python docs"
-copyright = "2022, Daniel Ciborowski"
-author = "Daniel Ciborowski"
-
-# The full version, including alpha/beta/rc tags
+project = "openpois"
+copyright = "2024, Nathaniel Henry"
+author = "Nathaniel Henry"
 release = "0.1.0"
 
+# -- General configuration -----------------------------------------------------
 
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.doctest",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.ifconfig",
-    "sphinx.ext.viewcode",  # Add links to highlighted source code
-    "sphinx.ext.napoleon",  # to render Google format docstrings
-    "sphinx.ext.githubpages",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# Mock heavy imports so Sphinx can parse docstrings without installing the
+# full conda environment in CI.
+autodoc_mock_imports = [
+    "torch",
+    "numpy",
+    "pandas",
+    "geopandas",
+    "shapely",
+    "fiona",
+    "pyosmium",
+    "osmium",
+    "duckdb",
+    "pyiceberg",
+    "pyarrow",
+    "config_versioned",
+    "ngeohash",
+    "requests",
+    "scipy",
+    "matplotlib",
+    "sklearn",
+    "overturemaps",
+    "plotnine",
+    "mizani",
+]
 
-# -- Options for HTML output -------------------------------------------------
+# Napoleon settings
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "sphinx_rtd_theme"
+# Autodoc settings
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# -- Options for HTML output ---------------------------------------------------
 
-# Napoleon settings
-napoleon_include_init_with_doc = True
-napoleon_include_private_with_doc = True
+html_theme = "sphinx_rtd_theme"

docs/index.rst

@@ -1,16 +1,18 @@
-.. ai-python docs documentation master file, created by
-   sphinx-quickstart on Thu May  5 14:06:45 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+openpois
+========
 
-Welcome to ai-python docs's documentation!
-==========================================
+A Python library for conflating Points of Interest (POIs) across
+OpenStreetMap, Overture Maps, and Foursquare OS Places, with utilities for
+modeling POI stability over time using historical OSM data.
+
+- **GitHub:** https://github.com/henryspatialanalysis/openpois
+- **Web map:** https://henryspatialanalysis.github.io/openpois/
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
-   modules
 
+   api
 
 Indices and tables
 ==================