docs: initial external docs site

Author: jippi

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+      - proper-docs
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: setup
+        run: task docs:deploy

.vscode/settings.json

@@ -12,5 +12,16 @@
   ],
   "[go]": {
     "editor.formatOnSave": true,
-  }
+  },
+  "yaml.schemas": {
+    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+  },
+  "yaml.customTags": [
+    "!ENV scalar",
+    "!ENV sequence",
+    "!relative scalar",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+  ]
 }

Dockerfile.docs

@@ -0,0 +1 @@
+FROM squidfunk/mkdocs-material

Taskfile.yml

@@ -27,6 +27,18 @@ tasks:
     generates:
       - ./scm-engine
 
+  docs:server:
+    desc: Run Docs dev server with live preview
+    cmds:
+      - docker build -t scm-engine-docs -f Dockerfile.docs .
+      - docker run --rm -it -p 8000:8000 -v ${PWD}:/docs scm-engine-docs serve -o --watch-theme -w /docs --dev-addr 0.0.0.0:8000
+
+  docs:deploy:
+    desc: Deploy GitHub pages docs
+    cmds:
+      - docker build -t scm-engine-docs -f Dockerfile.docs .
+      - docker run --rm -v ${PWD}:/docs scm-engine-docs gh-deploy --force
+
   test:
     desc: Run tests
     env:

docs/index.md

@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

mkdocs.yml

@@ -0,0 +1,4 @@
+site_name: SCM Engine Docs
+
+theme:
+  name: material