imporve documentation development

.github/workflows/docs-test.yml

@@ -1,27 +1,27 @@
 name: Test documentation build
 
-on: [pull_request]
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - pyproject.toml
+      - poetry.lock
 
 concurrency:
   group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+permissions:
+  id-token: write
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - name: Install python
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.x
-      - name: Setup cache
-        uses: actions/cache@v2
-        with:
-          key: ${{ github.ref }}
-          path: .cache
-      - name: Setup dependencies
-        run: pip install -r docs/requirements.txt
-      - name: Build docs
-        run: mkdocs build --strict
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - name: Run tests
+        run: nix develop --command -- poetry run mkdocs build --strict

.github/workflows/docs.yml

@@ -4,6 +4,10 @@ on:
   push:
     branches:
       - main
+    paths:
+      - 'docs/**'
+      - pyproject.toml
+      - poetry.lock
   workflow_dispatch:
 
 permissions:
@@ -17,19 +21,10 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - name: Install python
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.x
-      - name: Setup cache
-        uses: actions/cache@v2
-        with:
-          key: ${{ github.ref }}
-          path: .cache
-      - name: Setup dependencies
-        run: pip install -r docs/requirements.txt
-      - name: Build docs
-        run: mkdocs build --strict
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - name: Run tests
+        run: nix develop --command -- poetry run mkdocs build --strict
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
@@ -39,9 +34,6 @@ jobs:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    permissions:
-      pages: write
-      id-token: write
     runs-on: ubuntu-latest
     needs: build
     steps:

Makefile

@@ -52,3 +52,9 @@ compress: build
 generate:
 	rm -rf gen
 	buf generate proto
+
+docs-serve:
+	poetry run mkdocs serve
+
+docs-build:
+	poetry run mkdocs build

docs/requirements.txt

@@ -1,4 +0,0 @@
-cairosvg~=2.7.1
-mkdocs-material~=9.5.18
-mkdocs-minify-plugin~=0.7.1
-pillow~=10.1.0

flake.nix

@@ -90,6 +90,10 @@
           protoc-gen-grpc-gateway
           buf
           clang-tools # clang-format
+
+          # Docu dependencies
+          python311
+          poetry
         ];
 
       # Add entry to build a docker image with headscale

pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "docs"
+version = "0.1.0"
+description = ""
+authors = ["ohdearaugustin <ohdearaugustin@users.noreply.github.com>"]
+package-mode = false
+
+[tool.poetry.dependencies]
+python = "^3.11"
+cairosvg = "^2.7.1,<2.8.0"
+mkdocs = "^1.6.0,<1.7.0"
+mkdocs-material = "^9.4.14"
+mkdocs-minify-plugin = ">=0.7.1,<0.8.0"
+pillow = ">=10.1.0,<10.2.0"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"