add docstrings linter (#229)

Add docstring linter to Spoons repo

.github/workflows/PR.yml

@@ -56,6 +56,25 @@ jobs:
     - name: Show changed files
       run: cat $HOME/files.json
 
+    # Lint docstrings
+    - name: Docstrings Linter
+      run: ./gh_actions_doclint.sh
+
+    # Publish Docstring Annotations
+    - name: Publish Docstring Annotations
+      uses: yuzutech/annotations-action@v0.3.0
+      with:
+        repo-token: "${{ secrets.GITHUB_TOKEN }}"
+        title: "Docstrings linter"
+        input: annotations.json
+
+    # Fail CI run if docstrings failed
+    - name: Check for docstring lint failures
+      run: ./gh_actions_doclint.sh -v
+
+    - name: Remove annotations file
+      run: rm annotations.json
+
     # Update docs and zips
     - name: Update docs and zips
       run: ./gh_actions_publish.sh

.gitignore

@@ -1,3 +1,5 @@
 .docs_tmp
 *.swp
 hammerspoon/
+annotations/
+annotations.json

build_docs.sh

@@ -12,7 +12,7 @@ else
 fi
 
 mkdir -p .docs_tmp
-"${HAMMERSPOON_PATH}/scripts/docs/bin/build_docs.py" -e "${HAMMERSPOON_PATH}/scripts/docs/templates/" -o .docs_tmp -i "Hammerspoon Spoons" -j -t -n Source
+/usr/bin/python3 "${HAMMERSPOON_PATH}/scripts/docs/bin/build_docs.py" -e "${HAMMERSPOON_PATH}/scripts/docs/templates/" -o .docs_tmp -i "Hammerspoon Spoons" -j -t -n Source
 cp "${HAMMERSPOON_PATH}/scripts/docs/templates/docs.css" .docs_tmp/html/
 cp "${HAMMERSPOON_PATH}/scripts/docs/templates/jquery.js" .docs_tmp/html/
 mv .docs_tmp/html/* docs/

gh_actions_doclint.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+if [ "$GITHUB_ACTIONS" != "true" ]; then
+    echo "This script should only be run as part of a GitHub Action"
+    exit 1
+fi
+
+set -x
+
+if [ "$1" == "-v" ]; then
+    COUNT=$(jq length annotations.json)
+    if [ "${COUNT}" != "0" ]; then
+        exit 1
+    fi
+
+    exit 0
+fi
+
+set -eu
+
+# Find the Spoons that have been modified
+SPOONS=$(cat "${HOME}/files.json" | jq -r -c '.[] | select(contains(".lua"))' | sed -e 's#^Source/\(.*\).spoon/.*#\1#' | sort | uniq)
+
+if [ "${SPOONS}" == "" ]; then
+    echo "No Spoons modified, skipping doc linting"
+    exit 0
+fi
+
+mkdir -p annotations
+
+while IFS= read -r SPOON ; do
+    /usr/bin/python3 ./hammerspoon/scripts/docs/bin/build_docs.py -l -o annotations/ -n Source/${SPOON}.spoon/
+    mv annotations/annotations.json "annotations/${SPOON}-annotations.json"
+done <<< "${SPOONS}"
+
+jq -s '[.[][]]' annotations/*.json >annotations.json
+rm -rf annotations/
+

gh_actions_publish.sh

@@ -20,7 +20,7 @@ git config --global user.email "spoonPRbot@tenshu.net"
 git config --global user.name "Spoons GitHub Bot"
 
 while IFS= read -r SPOON ; do
-    ./hammerspoon/scripts/docs/bin/build_docs.py -e ./hammerspoon/scripts/docs/templates/ -o Source/${SPOON}.spoon/ -j -n Source/${SPOON}.spoon/
+    /usr/bin/python3 ./hammerspoon/scripts/docs/bin/build_docs.py -e ./hammerspoon/scripts/docs/templates/ -o Source/${SPOON}.spoon/ -j -n Source/${SPOON}.spoon/
     rm Source/${SPOON}.spoon/docs_index.json
     git add Source/${SPOON}.spoon/docs.json
     git commit -am "Generate docs for ${SPOON}" || true
@@ -29,7 +29,6 @@ while IFS= read -r SPOON ; do
     git add Spoons/${SPOON}.spoon.zip
     git commit -am "Add binary package for ${SPOON}."
     ./build_docs.sh
-    rm -rf ./hammerspoon/
     git add docs
     git commit --allow-empty -am "Update docs"
 done <<< "${SPOONS}"