docs: add basic docs about configuration and policies

.dockerignore

@@ -1,6 +1,7 @@
 .git
 .github
 .gitignore
+.venv
 
 chopsticks
 docs

.github/workflows/_job-docs-deploy.yml

@@ -0,0 +1,62 @@
+name: Deploy docs
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: "Documentation version to deploy (e.g., '0.5', 'dev')"
+        required: true
+        type: string
+      alias:
+        description: "Version alias (e.g., 'latest', 'dev')"
+        required: false
+        type: string
+      set_default:
+        description: "Set this version as the default landing page"
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: write # for mike to push to gh-pages
+
+jobs:
+  docs-deploy:
+    name: Deploy docs (${{ inputs.version }})
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install mkdocs-materialx mike
+
+      - name: Configure git user
+        # Using the official GitHub Actions bot identity (user ID 41898282).
+        # This shows the bot avatar on gh-pages commits.
+        # See: https://api.github.com/users/github-actions%5Bbot%5D
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Fetch gh-pages branch
+        run: git fetch origin gh-pages --depth=1 || true
+
+      - name: Deploy docs
+        run: |
+          if [ -n "${{ inputs.alias }}" ] && [ "${{ inputs.alias }}" != "${{ inputs.version }}" ]; then
+            mike deploy --push --update-aliases ${{ inputs.version }} ${{ inputs.alias }}
+          else
+            mike deploy --push ${{ inputs.version }}
+          fi
+
+      - name: Set default version
+        if: inputs.set_default
+        run: mike set-default --push ${{ inputs.alias || inputs.version }}

.github/workflows/merge-to-dev.yml

@@ -29,3 +29,10 @@ jobs:
     permissions:
       contents: read
       packages: write
+
+  docs-deploy:
+    uses: ./.github/workflows/_job-docs-deploy.yml
+    with:
+      version: dev
+    permissions:
+      contents: write

.github/workflows/release.yml

@@ -39,3 +39,13 @@ jobs:
       changelog_body: ${{ needs.prepare.outputs.changelog_body }}
     permissions:
       contents: write
+
+  docs-deploy:
+    needs: [prepare]
+    uses: ./.github/workflows/_job-docs-deploy.yml
+    with:
+      version: ${{ needs.prepare.outputs.version }}
+      alias: latest
+      set_default: true
+    permissions:
+      contents: write

.gitignore

@@ -11,6 +11,9 @@ static/
 # locally installed binaries
 /bin
 
+# python virtual environment
+/.venv
+
 # asset hub node metadata required for subxt compilation
 /metadata.scale
 

Makefile

@@ -145,3 +145,17 @@ generate-coverage-report: # Generate test coverage report as lcov.info
 
 open-coverage-report: # Generate and open test coverage report
 	PATH="${PWD}/bin:${PATH}" cargo llvm-cov nextest -p kalatori --open
+
+######################
+### Documentation  ###
+######################
+
+install-mkdocs: # Install mkdocs with material theme and mike into local .venv
+	python3 -m venv .venv
+	.venv/bin/pip install mkdocs-materialx mike
+
+docs-serve: # Serve documentation locally with live reload
+	.venv/bin/mkdocs serve --livereload -o
+
+docs-build: # Build documentation locally
+	.venv/bin/mkdocs build