diff --git a/doc/hugo/chapter.md.tmpl b/doc/hugo/chapter.md.tmpl new file mode 100644 index 0000000..5b4e815 --- /dev/null +++ b/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 %} + diff --git a/doc/hugo/config.toml b/doc/hugo/config.toml new file mode 100644 index 0000000..c5a8693 --- /dev/null +++ b/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' diff --git a/doc/hugo/generate-protocol-docs.sh b/doc/hugo/generate-protocol-docs.sh new file mode 100755 index 0000000..3be4402 --- /dev/null +++ b/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" - < /dev/null || exit 1 diff --git a/doc/hugo/interface.md.tmpl b/doc/hugo/interface.md.tmpl new file mode 100644 index 0000000..6ed1e82 --- /dev/null +++ b/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 %}