Refactor documentation workflow to build and deploy site to a dedicated branch, and remove outdated docs.

.github/workflows/docs.yml

@@ -1,4 +1,8 @@
-name: Deploy Docs
+# Deploy Docs to GitHub Pages using MkDocs
+# This workflow builds documentation from the 'docs/' folder using mkdocs.yml in the repo root
+# and deploys the static site to GitHub Pages.
+
+name: Build Docs and Push Site
 
 on:
   push:
@@ -6,7 +10,7 @@ on:
       - main
 
 jobs:
-  deploy:
+  build-and-push-site:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -14,14 +18,26 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: '3.11'
+      # Ensure mkdocs.yml exists in the repo root
+      - name: Check for mkdocs.yml in root
+        run: |
+          if [ ! -f mkdocs.yml ]; then
+            echo "Error: mkdocs.yml not found in repository root. Please add it." && exit 1
+          fi
       - name: Install dependencies
         run: |
           pip install -r docs/requirements.txt
-      - name: Build docs
+      - name: Build docs with MkDocs
         run: |
           mkdocs build
-      - name: Deploy to GitHub Pages
+      - name: Push site/ to site-artifact branch
-        uses: peaceiris/actions-gh-pages@v4
+        run: |
-        with:
+          git config --global user.name "github-actions[bot]"
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          publish_dir: ./site 
+          git fetch origin site-artifact || true
+          git switch --orphan site-artifact
+          git rm -rf .
+          cp -r site/* .
+          git add .
+          git commit -m "Update built site from main"
+          git push --force origin site-artifact 

docs/api.md

@@ -1,21 +0,0 @@
-# API Reference
-
-This page documents the main modules and functions of the `prettymaps` library. The API documentation is auto-generated from the code and includes all public classes and functions.
-
-## Modules
-
-- **draw**: Core drawing and plotting functions, including map rendering, layer management, and style handling.
-- **fetch**: Functions for fetching and processing OpenStreetMap data and elevation.
-- **utils**: Utility functions for logging, timing, and other helpers.
-
----
-
-::: prettymaps.draw
-
----
-
-::: prettymaps.fetch
-
----
-
-::: prettymaps.utils 

docs/index.md

@@ -1,27 +0,0 @@
-# prettymaps
-
-A minimal Python library to draw pretty maps from OpenStreetMap data.
-
-- [Usage](usage.md)
-- [API Reference](api.md)
-
-## Features
-- Draw beautiful maps from OSM data
-- Highly customizable layers and styles
-- Preset management
-- Keypoint highlighting
-
-## Installation
-```bash
-pip install prettymaps
-```
-
-## Quick Example
-```python
-import prettymaps
-prettymaps.plot("Porto Alegre")
-```
-
----
-
-Data © OpenStreetMap contributors 

docs/requirements.txt

@@ -1,4 +0,0 @@
-mkdocs
-mkdocs-material
-mkdocstrings
-mkdocstrings-python 

docs/usage.md

@@ -1,64 +0,0 @@
-# Usage
-
-## Basic Usage
-
-The main entry point is the `plot()` function:
-
-```python
-import prettymaps
-prettymaps.plot("Porto Alegre")
-```
-
-This will generate a map for the given location using default layers and styles.
-
-## Customizing Layers and Styles
-
-You can customize which OpenStreetMap layers are shown and how they are styled:
-
-```python
-layers = {
-    "perimeter": {},
-    "streets": {"width": 8},
-    "buildings": {},
-}
-style = {
-    "perimeter": {"fc": "#f2efe9"},
-    "streets": {"fc": "#cccccc", "ec": "#333333"},
-    "buildings": {"fc": "#bdbdbd"},
-}
-prettymaps.plot("Porto Alegre", layers=layers, style=style)
-```
-
-## Using Presets
-
-Presets are reusable configurations for layers and styles. You can load, save, or update presets:
-
-```python
-prettymaps.plot("Porto Alegre", preset="default")
-```
-
-You can also create your own presets and save them for later use.
-
-## Highlighting Keypoints
-
-You can highlight specific keypoints (e.g., landmarks) on the map:
-
-```python
-keypoints = {
-    "tags": {"tourism": "attraction"},
-    "kwargs": {"bbox": {"fc": "yellow"}},
-}
-prettymaps.plot("Porto Alegre", keypoints=keypoints)
-```
-
-## Saving Maps
-
-You can save the generated map to a file:
-
-```python
-prettymaps.plot("Porto Alegre", save_as="map.png")
-```
-
----
-
-See the [API Reference](api.md) for details on all functions and parameters.