Migrate docs build to MkDocs

.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements_dev.txt'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements_dev.txt'
+      - '.github/workflows/docs.yml'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements_dev.txt
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: gunicorn-site
+          path: site
+          retention-days: 7
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements_dev.txt
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site
+          publish_branch: gh-pages
+          commit_message: "docs: deploy {sha}"

.gitignore

@@ -16,3 +16,5 @@ examples/frameworks/pylonstest/pylonstest.egg-info/
 MANIFEST
 nohup.out
 setuptools-*
+site/
+docs/site/

Makefile

@@ -9,9 +9,15 @@ test:
 coverage:
 	venv/bin/python setup.py test --cov
 
+docs:
+	mkdocs build
+
+docs-serve:
+	mkdocs serve
+
 clean:
 	@rm -rf .Python MANIFEST build dist venv* *.egg-info *.egg
 	@find . -type f -name "*.py[co]" -delete
 	@find . -type d -name "__pycache__" -delete
 
-.PHONY: build clean coverage test
+.PHONY: build clean coverage docs docs-serve test

docs/README.rst

@@ -4,16 +4,26 @@ Generate Documentation
 Requirements
 ------------
 
-To generate documentation you need to install:
+Install the documentation dependencies with::
 
- - Python >= 3.7
- - Sphinx (https://www.sphinx-doc.org/)
+    pip install -r requirements_dev.txt
 
+This provides MkDocs with the Material theme and supporting plugins.
 
-Generate html
--------------
+
+Build static HTML
+-----------------
+::
+
+    mkdocs build
+
+The rendered site is emitted into the ``site/`` directory.
+
+
+Preview locally
+---------------
 ::
 
-    $ make html
+    mkdocs serve
 
-The command generates html document inside ``build/html`` dir.
+This serves the documentation at http://127.0.0.1:8000/ with live reload.