From 971d7c55a0b3a1581fbcaa58d116d78097b562d9 Mon Sep 17 00:00:00 2001
From: Marcelo Prates <marceloorp@gmail.com>
Date: Fri, 16 May 2025 21:56:24 -0300
Subject: [PATCH] Refactor documentation workflow to build and deploy site to a
 dedicated branch, and remove outdated docs.

---
 .github/workflows/docs.yml | 32 ++++++++++++++-----
 docs/api.md                | 21 -------------
 docs/index.md              | 27 ----------------
 docs/requirements.txt      |  4 ---
 docs/usage.md              | 64 --------------------------------------
 5 files changed, 24 insertions(+), 124 deletions(-)
 delete mode 100644 docs/api.md
 delete mode 100644 docs/index.md
 delete mode 100644 docs/requirements.txt
 delete mode 100644 docs/usage.md

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index a13f7a3..46395be 100644
--- a/.github/workflows/docs.yml
+++ b/.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
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site 
\ No newline at end of file
+      - name: Push site/ to site-artifact branch
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          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 
\ No newline at end of file
diff --git a/docs/api.md b/docs/api.md
deleted file mode 100644
index deb325e..0000000
--- a/docs/api.md
+++ /dev/null
@@ -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 
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index d5d7266..0000000
--- a/docs/index.md
+++ /dev/null
@@ -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 
\ No newline at end of file
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index f105c8b..0000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-mkdocs
-mkdocs-material
-mkdocstrings
-mkdocstrings-python 
\ No newline at end of file
diff --git a/docs/usage.md b/docs/usage.md
deleted file mode 100644
index 7954f06..0000000
--- a/docs/usage.md
+++ /dev/null
@@ -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. 
\ No newline at end of file