doc: add the templates and a script to generate hugo markdown

Intention here is to have the protocol in a readable manner somewhere.
Doxygen doesn't *quite* cut the bill.

doc/hugo/chapter.md.tmpl

@@ -0,0 +1,12 @@
+{% for chapter in documentation.chapters %}
+{% if chapter.title == extra.title %}
+---
+title: "{{chapter.title}}"
+draft: false
+---
+
+{{chapter.text|ei_escape_names}}
+
+{% endif %}
+{% endfor %}
+

doc/hugo/config.toml

@@ -0,0 +1,4 @@
+baseURL = 'https://libinput.pages.freedesktop.org/libei/'
+languageCode = 'en-us'
+title = 'ei protocol documentation'
+theme = 'hugo-theme-relearn'

doc/hugo/generate-protocol-docs.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+#
+set -e
+
+
+SCANNER="$PWD/ei-scanner"
+PROTOFILE="$PWD/protocol.xml"
+TEMPLATEDIR="$PWD"
+OUTDIR="$PWD"
+SITENAME="ei"
+INDEXPAGE=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --verbose | -v)
+      set -x
+      shift
+      ;;
+    --scanner)
+      SCANNER="$2"
+      shift 2;
+      ;;
+    --protocol)
+      PROTOFILE="$2"
+      shift 2
+      ;;
+    --template-dir)
+      TEMPLATEDIR="$2"
+      shift 2
+      ;;
+    --output-dir)
+      OUTDIR="$2"
+      shift 2
+      ;;
+    --index-page)
+      INDEXPAGE="$2"
+      shift 2;
+      ;;
+    **)
+      echo "Unknown argument: $1"
+      exit 1
+      ;;
+  esac
+done
+
+SITEDIR="$OUTDIR/$SITENAME"
+if [[ -e "$SITEDIR" ]]; then
+  echo "$SITEDIR already exists, updating"
+else
+  hugo new site "$SITEDIR"
+  git clone --depth=1 https://github.com/McShelby/hugo-theme-relearn "$SITEDIR/themes/hugo-theme-relearn"
+fi
+
+cp "$TEMPLATEDIR/config.toml" "$SITEDIR/"
+if [[ -n "$INDEXPAGE" ]]; then
+  cp "$INDEXPAGE" "$SITEDIR/content/_index.md"
+fi
+
+pushd "$SITEDIR" > /dev/null || exit 1
+
+# Generate a list of available interfaces and read that
+# list line-by-line to generate a separate .md file
+# for each interface
+mkdir -p "$SITEDIR/content/interfaces"
+while read -r iface; do
+  $SCANNER --component=ei --jinja-extra-data="{ \"interface\": \"$iface\" }" --output="$SITEDIR/content/interfaces/$iface.md" "$PROTOFILE" "$TEMPLATEDIR/interface.md.tmpl"
+done < <($SCANNER --component=ei "$PROTOFILE" - <<EOF
+{% for interface in interfaces %}
+{{interface.name}}
+{% endfor %}
+EOF
+)
+
+# Generate a list of available chapters and read that
+# list line-by-line to generate a separate .md file
+# for each chapter
+mkdir -p "$SITEDIR/content/doc"
+while read -r title; do
+  $SCANNER --component=ei --jinja-extra-data="{ \"title\": \"$title\" }" --output="$SITEDIR/content/doc/$title.md" "$PROTOFILE" "$TEMPLATEDIR/chapter.md.tmpl"
+done < <($SCANNER --component=ei "$PROTOFILE" - <<EOF
+{% for chapter in documentation.chapters %}
+{{chapter.title}}
+{% endfor %}
+EOF
+)
+
+popd > /dev/null || exit 1

doc/hugo/interface.md.tmpl

@@ -0,0 +1,93 @@
+{% for interface in interfaces %}
+{% if interface.name == extra.interface %}
+---
+title: "{{interface.name}}"
+draft: false
+---
+
+# {{interface.description.summary|title}}
+
+
+{{interface.description.text|ei_escape_names}}
+
+
+{% if interface.enums %}
+# Enums
+
+{% raw %}
+{{% notice style="info" %}}
+Enum names are shown here in uppercase. The exact name depends on the language bindings.
+{{% /notice %}}
+{% endraw %}
+
+{% for enum in interface.enums %}
+## {{interface.name}}.{{enum.name}}
+
+{{enum.description.text|ei_escape_names}}
+
+| Name | Value | Summary |
+| ---- | ----- | ------- |
+{% for entry in enum.entries %}
+| `{{entry.name|upper}}` | {{entry.value}} | {{entry.summary}} |
+{% endfor %}
+
+{% endfor %}
+{% endif %}
+
+
+{% if interface.requests %}
+# Requests
+
+{% for request in interface.requests %}
+
+## {{interface.name}}.{{request.name}}
+
+{% raw %}{{% badge style="primary" title="Since Version" %}}{% endraw %}{{request.since}}{% raw %}{{% /badge %}}{% endraw %}
+
+{% raw %}{{% badge style="secondary" title="Request Opcode" %}}{% endraw %}{{request.opcode}}{% raw %}{{% /badge %}}{% endraw %}
+
+```
+{{interface.name}}.{{request.name}}({{request.arguments|join(", ", attribute="name")}})
+```
+
+{% if request.arguments %}
+| Argument | Type | Summary |
+| -------- | ---- | ------- |
+{% for arg in request.arguments %}
+| {{arg.name}} | `{{arg.protocol_type}}` | {{arg.summary}} |
+{% endfor %}
+{% endif %}
+
+{{request.description.text|ei_escape_names}}
+
+{% endfor %}
+{% endif %}
+
+{% if interface.events %}
+# Events
+{% for event in interface.events %}
+## {{interface.name}}.{{event.name}}
+
+{% raw %}{{% badge style="primary" title="Since Version" %}}{% endraw %}{{event.since}}{% raw %}{{% /badge %}}{% endraw %}
+
+{% raw %}{{% badge style="secondary" title="Event Opcode" %}}{% endraw %}{{event.opcode}}{% raw %}{{% /badge %}}{% endraw %}
+
+```
+{{interface.name}}.{{event.name}}({{event.arguments|join(", ", attribute="name")}})
+```
+{% if event.arguments %}
+| Argument| Type | Summary |
+| ------- | ---- | ------- |
+{% for arg in event.arguments %}
+| {{arg.name}} | `{{arg.protocol_type}}` | {{arg.summary}} |
+{% endfor %}
+{% endif %}
+
+{{event.description.text|ei_escape_names}}
+
+{% endfor %}
+{% endif %}
+
+
+{% endif %}
+{% endfor %}