feat: add engine docs to docs.ooni.org

.github/workflows/build_docs.yml

@@ -0,0 +1,46 @@
+name: build docs
+on: push
+
+jobs:
+  build_docs:
+    runs-on: "ubuntu-20.04"
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v3
+
+      - name: Build docs
+        run: make docs
+
+      - name: Get current git ref
+        id: rev_parse
+        run: echo "COMMIT_HASH=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Checkout ooni/docs
+        uses: actions/checkout@v2
+        with:
+          repository: "ooni/docs"
+          ssh-key: ${{ secrets.OONI_DOCS_DEPLOYKEY }}
+          path: "ooni-docs"
+
+      - name: Update docs
+        run: cp -R dist/docs/* ooni-docs/src/content/docs/mydocs/
+
+      - name: Check for conflicting slugs
+        run: |
+          cat ooni-docs/src/content/docs/mydocs/*.md \
+            | grep "^slug:" | awk -F':' '{gsub(/^ +/, "", $2); print $2}' | sort | uniq -c \
+            | awk '{if ($1 > 1) { print "duplicate slug for: " $2; exit 1}}'
+
+      - name: Print the lines of the generated docs
+        run: wc -l ooni-docs/src/content/docs/mydocs/*
+
+      - name: Commit changes
+        # Only push the docs update when we are in master
+        if: github.ref == 'refs/heads/master'
+        run: |
+          cd ooni-docs
+          git config --global user.email "[email protected]"
+          git config --global user.name "OONI Github Actions Bot"
+          git add .
+          git commit -m "auto: update backend docs to ${{ steps.rev_parse.outputs.COMMIT_HASH }}" || echo "No changes to commit"
+          git push origin

Makefile

@@ -117,3 +117,12 @@ search/for/xcode:
 search/for/zip:
 	@printf "checking for zip... "
 	@command -v zip || { echo "not found"; exit 1; }
+
+#help:
+#help: The `make docs clean` commanfd build the docs for docs.ooni.org.
+.PHONY: docs clean
+docs:
+	./scripts/build_docs.sh
+
+clean:
+	rm -rf dist/

scripts/build_docs.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+DOCS_ROOT=dist/docs/
+REPO_NAME="ooni/probe-cli"
+COMMIT_HASH=$(git rev-parse --short HEAD)
+
+mkdir -p $DOCS_ROOT
+
+strip_title() {
+    # Since the title is already present in the frontmatter, we need to remove
+    # it to avoid duplicate titles
+    local infile="$1"
+    cat $infile | awk 'BEGIN{p=1} /^#/{if(p){p=0; next}} {print}'
+}
+
+cat <<EOF>$DOCS_ROOT/00-index.md
+---
+# Do not edit! This file is automatically generated
+# to edit go to: https://github.com/$REPO_NAME/edit/master/README.md
+# version: $REPO_NAME:$COMMIT_HASH 
+---
+EOF