Add mkdocs targets and publishing workflow

Author: f-PLT

.github/workflows/publish-gh-pages.yml

@@ -0,0 +1,52 @@
+name: Publish gh-pages
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  Publish-gh-pages:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Poetry
+        run: |
+          pip install poetry
+
+      - name: Cache Poetry virtualenv and dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry
+            ~/.cache/pip
+          key: poetry-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            poetry-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: |
+          make install
+
+      - name: Run mkdocs deploy
+        run: |
+          poetry run mkdocs gh-deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Makefile.targets

@@ -5,4 +5,34 @@
 
 .PHONY: test-notebooks
 test-notebooks: ## Execute test notebooks using pytest and nbval
-	$(ENV_COMMAND_TOOL) nox -s test_nb
+	$(ENV_COMMAND_TOOL) nox -s test_nb
+
+## -- Docs targets -------------------------------------------------------------------------------------------------- ##
+.PHONY: preview-docs
+preview-docs: ## Preview the documentation site locally
+	@poetry run mkdocs serve -a 0.0.0.0:7000
+
+
+.PHONY: build-docs
+build-docs: ## Build the documentation files locally
+	@poetry run mkdocs build
+
+.PHONY: deploy-docs
+deploy-docs: ## Publish and deploy the documentation to the live Github page
+	@echo""; \
+	echo -e "\e[1;39;41m-- WARNING --\e[0m This command will deploy all current changes to the live Github page - Making it publicly available"; \
+	echo""; \
+	echo -n "Would you like to deploys the docs? [Y/n]: "; \
+	read ans; \
+	case $$ans in \
+		[Yy]*) \
+			echo""; \
+			poetry run mkdocs gh-deploy; \
+			echo""; \
+			;; \
+		*) \
+			echo""; \
+			echo "Skipping publication to Github Pages."; \
+			echo " "; \
+			;; \
+	esac; \