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/probe-engine/
+
+      - name: Check for conflicting slugs
+        run: |
+          cat ooni-docs/src/content/docs/probe-engine/*.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/probe-engine/*
+
+      - 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` command builds the docs for docs.ooni.org.
+.PHONY: docs clean
+docs:
+	./script/build_docs.sh
+
+clean:
+	rm -rf dist/

script/build_docs.sh

@@ -0,0 +1,187 @@
+#!/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
+title: OONI Probe Engine
+description: OONI Probe Engine documentation
+slug: probe-engine
+---
+EOF
+strip_title README.md >> $DOCS_ROOT/00-index.md
+
+# design docs
+BASE_PATH=docs/design
+
+DOC_PATH=$DOCS_ROOT/00-design.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI Probe Engine Design
+description: Design documents for OONI Probe
+slug: probe-engine/design/
+---
+EOF
+strip_title $BASE_PATH/README.md >> $DOC_PATH
+
+DOC_PATH=$DOCS_ROOT/01-design-oonimkall.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI oonimkall 
+description: OONI oonimkall package design documentaton
+slug: probe-engine/design/oonimkall
+---
+EOF
+strip_title $BASE_PATH/dd-001-oonimkall.md >> $DOC_PATH
+
+DOC_PATH=$DOCS_ROOT/02-design-netx.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI netx
+description: OONI netx package design documentation
+slug: probe-engine/design/netx
+---
+EOF
+strip_title $BASE_PATH/dd-02-netx.md >> $DOC_PATH
+
+DOC_PATH=$DOCS_ROOT/03-design-step-by-step.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI step-by-step
+description: OONI step-by-step design documentation
+slug: probe-engine/design/step-by-step
+---
+EOF
+strip_title $BASE_PATH/dd-003-step-by-step.md >> $DOC_PATH
+
+DOC_PATH=$DOCS_ROOT/04-design-minioonirunv2.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI minioonirunv2
+description: OONI minioonirunv2 design documentation
+slug: probe-engine/design/minioonirunv2
+---
+EOF
+strip_title $BASE_PATH/dd-004-minioonirunv2.md >> $DOC_PATH
+
+DOC_PATH=$DOCS_ROOT/05-design-dslx.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI dslx
+description: OONI dslx package design documentation
+slug: probe-engine/design/dslx
+---
+EOF
+strip_title $BASE_PATH/dd-005-dslx.md >> $DOC_PATH
+
+DOC_PATH=$DOCS_ROOT/06-design-probeservices.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI probeservices
+description: OONI probeservices design documentation
+slug: probe-engine/design/probeservices
+---
+EOF
+strip_title $BASE_PATH/dd-006-probeservices.md >> $DOC_PATH
+
+DOC_PATH=$DOCS_ROOT/07-design-throttling.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI throttling experiment
+description: OONI throttling experiment design documentation
+slug: probe-engine/design/throttling
+---
+EOF
+strip_title $BASE_PATH/dd-007-throttling.md >> $DOC_PATH
+
+DOC_PATH=$DOCS_ROOT/08-design-richer-input.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI richer input
+description: OONI richer input design documentation
+slug: probe-engine/design/richer-input
+---
+EOF
+strip_title $BASE_PATH/dd-008-richer-input.md >> $DOC_PATH
+
+# oonimkall docs
+DOC_PATH=$DOCS_ROOT/09-oonimkall.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI oonimkall
+description: OONI oonimkall documentation
+slug: probe-engine/oonimkall
+---
+EOF
+strip_title pkg/oonimkall/README.md >> $DOC_PATH
+
+# release docs
+DOC_PATH=$DOCS_ROOT/10-releasing.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI Probe Release
+description: OONI Probe release documentation
+slug: probe-engine/releasing/
+---
+EOF
+strip_title docs/releasing.md >> $DOC_PATH
+
+# release docs
+DOC_PATH=$DOCS_ROOT/10-releasing.md
+cat <<EOF>$DOC_PATH
+---
+# 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
+title: OONI Probe Release
+description: OONI Probe release documentation
+slug: probe-engine/releasing/
+---
+EOF
+strip_title docs/releasing.md >> $DOC_PATH