Revival 4/4: MkDocs documentation (Material + mkdocstrings) replacing Sphinx

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Docs
+
+on:
+  push:
+    branches: [master]
+    paths: ["docs/**", "mkdocs.yml", "src/**", "CHANGELOG.md", "CONTRIBUTING.md", ".github/workflows/docs.yml"]
+  pull_request:
+    paths: ["docs/**", "mkdocs.yml", "src/**", "CHANGELOG.md", "CONTRIBUTING.md", ".github/workflows/docs.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build (strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install -e ".[docs]"
+      - run: mkdocs build --strict
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install -e ".[docs]"
+      - name: Publish to the gh-pages branch
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          mkdocs gh-deploy --force --no-history

.gitignore

@@ -11,3 +11,4 @@ dist/
 .coverage
 htmlcov/
 .ruff_cache/
+site/

CHANGELOG.md

@@ -24,6 +24,8 @@ versions of pandas (>= 2.2), GeoPandas (>= 1.0), scikit-learn and statsmodels.
   `pipeline.generate_testdata(..., seed=...)`.
 - `PredictionPipeline.features`, `.next_time` and `random_state`.
 - Test suite (pytest) and continuous integration for Python 3.10-3.13.
+- Documentation rebuilt with MkDocs (Material + mkdocstrings), deployed
+  automatically to GitHub Pages; replaces the Sphinx site.
 - `pyproject.toml` packaging (src layout) and automated PyPI publishing.
 
 ### Changed
@@ -39,6 +41,7 @@ versions of pandas (>= 2.2), GeoPandas (>= 1.0), scikit-learn and statsmodels.
 - `geojsoncontour` is an optional dependency (`pip install predspot[contour]`).
 
 ### Removed
+- Sphinx documentation sources and the committed HTML build.
 - `QuadratCount2`, `KGrid` and the hard dependencies on `descartes`,
   `contextily` and `rtree`.
 

CONTRIBUTING.md

@@ -22,6 +22,20 @@ PREDSPOT_NETWORK_TESTS=1 pytest tests/test_load_study_area.py  # also query Open
 
 CI runs the same checks on Python 3.10 to 3.13 for every pull request.
 
+## Documentation
+
+The site is built with [MkDocs](https://www.mkdocs.org/) and
+[Material](https://squidfunk.github.io/mkdocs-material/); API pages come from the
+docstrings via mkdocstrings.
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve            # live preview at http://127.0.0.1:8000
+mkdocs build --strict   # what CI runs
+```
+
+Pushing to `master` deploys the site to GitHub Pages automatically.
+
 ## Releasing
 
 1. Bump `__version__` in `src/predspot/__init__.py` and update `CHANGELOG.md`.

README.md

@@ -26,7 +26,8 @@ implementation and adapt it to your own data.
 
 ## How to use? 🚀
 
-> Documentation under construction.
+Full documentation, with a quickstart, a user guide and the API reference, lives at
+**https://adaj.github.io/predspot/**.
 
 Basic usage example:
 

docs/api/crime_mapping.md

@@ -0,0 +1 @@
+::: predspot.crime_mapping

docs/api/dataset_preparation.md

@@ -0,0 +1 @@
+::: predspot.dataset_preparation

docs/api/feature_engineering.md

@@ -0,0 +1 @@
+::: predspot.feature_engineering

docs/api/ml_modelling.md

@@ -0,0 +1 @@
+::: predspot.ml_modelling

docs/api/pipeline.md

@@ -0,0 +1 @@
+::: predspot.pipeline

docs/api/predspot.md

@@ -0,0 +1,16 @@
+# predspot
+
+The top-level package re-exports the most used objects:
+
+```python
+from predspot import (
+    Dataset, PredictionPipeline, PandasFeatureUnion,
+    KDE, QuadratCount, create_gridpoints, create_gridhexagonal, create_gridsquares,
+    load_study_area, generate_crimes,
+)
+```
+
+::: predspot
+    options:
+      members: false
+      show_source: false

docs/api/synthetic.md

@@ -0,0 +1 @@
+::: predspot.synthetic

docs/api/utilities.md

@@ -0,0 +1 @@
+::: predspot.utilities