diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 0000000000..0077b60256 --- /dev/null +++ b/.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 "github+backend@ooni.org" + 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 diff --git a/Makefile b/Makefile index 85ce2b33ae..88496448a4 100644 --- a/Makefile +++ b/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/ diff --git a/script/build_docs.sh b/script/build_docs.sh new file mode 100644 index 0000000000..6644ec450a --- /dev/null +++ b/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 <$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 <$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 <$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 <$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 <$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 <$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 <$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 <$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 <$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 <$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 <$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 <$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 <$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