docs: initial external docs site (#16)

* docs: initial external docs site

* ci: change workflow titles

* docs: add site/edit url

* docs: playing around with formatting

* docs: more playing around with naming

* fix: merge_request.state must be a string for working with 'in' operator

* docs: sync config file

* docs: more tuning of docs

* docs: split up script attributes and functions

* docs: rework things a bit more

* docs: generate attributes from source

* docs: improve UX

* docs: fix label/id for headlines

* docs: minor tweaks

* docs: expand docs and style it proper

* docs: pretty README.md

* docs: pretty README.md

* docs: pretty README.md

* docs: pretty README.md

* docs: pretty README.md

* ci: only ship docs on main brancH

Author: jippi

.github/workflows/docs.yml

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

.gitignore

@@ -1,17 +1,19 @@
-.direnv
-.env
-.env.*
-.idea/
-.scm-engine.yml
-.task/
-3rd-party/
-bin/
-completions/
-coverage.txt
-dist/
-/schema/ignore
-manpages/
-scm-engine
-scm-engine.exe
 *.gen.go
-!.env.example
+/.cache
+/.direnv
+/.env
+/.env.*
+/.idea/
+/.scm-engine.docs.yml
+/.scm-engine.yml
+/.task/
+/3rd-party/
+/bin/
+/completions/
+/coverage.txt
+/dist/
+/manpages/
+/schema/ignore
+/scm-engine
+/scm-engine.exe
+/docs/gitlab/script-attributes.md

.markdownlint.yml

@@ -0,0 +1,3 @@
+MD046: false
+MD013: false
+MD051: false

.scm-engine.example.yml

@@ -2,8 +2,8 @@
 
 actions:
   - name: Warn if the Merge Request haven't had commit activity for 21 days and will be closed
-    if: |
-      merge_request.state != "closed"
+    if: |1
+         merge_request.state != "closed"
       && merge_request.time_since_last_commit > duration("21d")
       && merge_request.time_since_last_commit < duration("28d")
       && not merge_request.has_label("do-not-close")
@@ -18,8 +18,8 @@ actions:
           To disable this behavior, add the `do-not-close` label to the Merge Request in the right menu or add a comment with `/label ~"do-not-close"`.
 
   - name: Close the Merge Request if it haven't had commit activity for 28 days
-    if: |
-      merge_request.state != "closed"
+    if: |1
+         merge_request.state != "closed"
       && merge_request.time_since_last_commit > duration("28d")
       && not merge_request.has_label("do-not-close")
     then:
@@ -34,8 +34,8 @@ actions:
           To disable this behavior, add the `do-not-close` label to the Merge Request in the right menu or add a comment with `/label ~"do-not-close"`.
 
   - name: Approve MR if the 'break-glass-approve' label is configured
-    if: |
-      merge_request.state != "closed"
+    if: |1
+         merge_request.state != "closed"
       && not merge_request.approved
       && merge_request.has_label("break-glass-approve")
     then:

.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,6 @@
+FROM squidfunk/mkdocs-material
+
+# https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin
+RUN pip install mkdocs-awesome-pages-plugin
+RUN pip install mkdocs-git-revision-date-localized-plugin
+RUN pip install mkdocs-git-authors-plugin