Auto-deploy documentation

Author: amrabed

.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Publish documentation to GitHub Pages
+on:
+  workflow_call:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Install dependencies
+        run: pip install mkdocs-material mkdocstrings[python]
+      - name: Publish to GitHub Pages
+        run: mkdocs gh-deploy --force

Makefile

@@ -51,8 +51,8 @@ coverage:
 test: coverage
 
 .PHONY: docs
-docs: # Build documentation site
-	poetry run mkdocs build
+docs: # Build and deploy documentation to GitHub pages
+	poetry run mkdocs gh-deploy --force
 
 local: # Serve documentation on a local server
 	poetry run mkdocs serve

docs/README.md

@@ -14,6 +14,7 @@ A Python project template that comes out of the box with configuration for:
 - Automated dependency update using [Dependabot](https://docs.github.com/en/code-security/dependabot)
 - Dockerized development environment using [Dev containers](https://code.visualstudio.com/docs/devcontainers/containers)
 - Automatic documentation from code using [mkdocs](https://www.mkdocs.org) and [mkdocstrings](https://mkdocstrings.github.io)
+- Documentation auto-deployment to [GiHub Pages](https://pages.github.com)
 - App container using [Docker](https://docker.com)
 
 ## How to use
@@ -112,10 +113,14 @@ docker compose run app -h
 ```
 
 ## Generating documentation
-To generate the project documentation, run:
+To generate and publish the project documentation to GitHub pages, run:
 ```bash
 make docs
 ```
+That pushes the new documentation to the gh-pages branch. 
+Make sure GitHub Pages is enableed in your repository settings and using the gh-pages branch for the documentation to be publicly available.
+
+### Local
 To serve the documentation on a local server, run:
 ```bash
 make local
@@ -131,7 +136,8 @@ make local
 │   ├── dependabot.yaml      # Dependabot configuration
 │   ├── FUNDING.md           # GitHub funding
 │   └── workflows            # Github Actions Workflows
-│       └── check.yml        # Workflow to validate code on push
+|       ├── check.yml        # Workflow to validate code on push
+│       └── docs.yml         # Woukflow to publish documentation
 ├── .gitignore               # Git-ignored file list
 ├── .pre-commit-config.yaml  # Pre-commit configuration file
 ├── .flake8                  # flake8 configuration file

mkdocs.yml

@@ -22,7 +22,6 @@ theme:
   - search.suggest
   - toc.follow
 
-
 nav:
   - Overview: README.md
   - Reference: