chore: Update docs website and publishing script (#10)

* Update docs website

* Add API docs

* update docs publish script

* lint docs

* update contributing docs

Author: kylebarron

.github/workflows/ci.yml

@@ -21,9 +21,8 @@ jobs:
         with:
           version: "latest"
 
-      # Ensure docs build without warnings
-      # - name: Check docs
-      #   run: uv run --group docs mkdocs build --strict
+      - name: Ensure docs build without warnings
+        run: uv run --group docs mkdocs build --strict
 
       # Use ruff-action so we get annotations in the Github UI
       - uses: astral-sh/ruff-action@v3

.github/workflows/deploy_mkdocs.yml

@@ -1,34 +1,57 @@
-name: Publish docs via GitHub Pages
+name: Publish Python docs
 
+# Only run on new tags starting with `v`
 on:
   push:
-    branches:
-      - main
-    paths:
-      # Only rebuild website when docs have changed
-      - 'README.md'
-      - 'docs/**'
-      - 'mkdocs.yml'
-      - 'rio_stac/**.py'
-      - .github/workflows/deploy_mkdocs.yml
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+# https://stackoverflow.com/a/77412363
+permissions:
+  contents: write
+  pages: write
 
 jobs:
   build:
-    name: Deploy docs
+    name: Deploy Python docs
     runs-on: ubuntu-latest
+    # Used for configuring social plugin in mkdocs.yml
+    # Unclear if this is always set in github actions
+    env:
+      CI: "TRUE"
     steps:
-      - name: Checkout main
-        uses: actions/checkout@v5
+      - uses: actions/checkout@v4
+        # We need to additionally fetch the gh-pages branch for mike deploy
+        with:
+          fetch-depth: 0
 
-      - name: Set up Python 3.12
-        uses: actions/setup-python@v6
+      - uses: astral-sh/setup-uv@v5
         with:
-          python-version: 3.12
+          enable-cache: true
 
-      - name: Install dependencies
+      - name: Deploy docs
+        env:
+          GIT_COMMITTER_NAME: CI
+          GIT_COMMITTER_EMAIL: ci-bot@example.com
         run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e .["doc"]
+          # Get most recent git tag
+          # https://stackoverflow.com/a/7261049
+          # https://stackoverflow.com/a/3867811
+          # We don't use {{github.ref_name}} because if triggered manually, it
+          # will be a branch name instead of a tag version.
+          VERSION=$(git describe --tags --match="v*" --abbrev=0)
+          echo $VERSION
 
-      - name: Deploy docs
-        run: mkdocs gh-deploy -f docs/mkdocs.yml --force
+          # Only push publish docs as latest version if no letters in git tag
+          # after the first character
+          # (usually the git tag will have v as the first character)
+          # Note the `cut` index is 1-ordered
+          if echo $VERSION | cut -c 2- | grep -q "[A-Za-z]"; then
+            echo "Is beta version"
+            # For beta versions publish but don't set as latest
+            uv run --group docs mike deploy $VERSION --update-aliases --push
+          else
+            echo "Is NOT beta version"
+            uv run --group docs mike deploy $VERSION latest --update-aliases --push
+          fi

CHANGES.md CHANGELOG.mdCHANGES.md renamed to CHANGELOG.md

@@ -23,3 +23,15 @@ This repo is set to use `pre-commit` to run *isort*, *flake8*, *pydocstring*, *b
 ```bash
 $ pre-commit install
 ```
+
+## Documentation
+
+### Building locally
+
+```
+uv run --group docs mkdocs serve
+```
+
+### Publishing docs
+
+Documentation is automatically published when a new tag with `v*` is pushed to `main`. Alternatively, you can manually publish docs by triggering the docs publish workflow from the GitHub actions UI.

CONTRIBUTING.md DEVELOP.mdCONTRIBUTING.md renamed to DEVELOP.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/CHANGELOG.md

@@ -0,0 +1 @@
+../DEVELOP.md

docs/DEVELOP.md

@@ -0,0 +1,3 @@
+# API Documentation
+
+::: async_pmtiles

docs/api.md

@@ -0,0 +1,2 @@
+# Blog
+