Fix readability script (#1063)

.github/workflows/validate-documentation.yml

@@ -89,33 +89,33 @@ jobs:
 
   report-readability:
     if: ${{ github.repository == 'grafana/writers-toolkit' }}
+
+    container:
+      image: grafana/vale:latest@sha256:55bf7dcba4ceac896b55225084bdb0b27e2e2f70c1398313bee13cb45eb60a95
     name: Report readability
     runs-on: ubuntu-latest
     steps:
-      - name: Install Vale
-        run: |
-          mkdir src
-          cd src
-          wget https://github.com/errata-ai/vale/releases/download/v2.28.0/vale_2.28.0_Linux_64-bit.tar.gz
-          tar zxf vale_2.28.0_Linux_64-bit.tar.gz vale
-          sudo cp vale /usr/local/bin/
-          cd ..
-          rm -rf src
-
       - name: Check out repository with history
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           fetch-depth: 0
           persist-credentials: false
 
+      - name: Install Bash
+        run: apk add bash
+
       - name: Run tool
         env:
-          SHA: ${{ github.event.pull_request.head.sha }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
         run: |
+          (cd /etc/vale && vale sync)
+          git config --global --add safe.directory /__w/writers-toolkit/writers-toolkit
           touch .output.txt
-          for file in $(git --no-pager diff --name-only --diff-filter=ACMRT origin/main -- docs/sources); do
-            ./scripts/readability "${file}" origin/main ${SHA} >> .output.txt
+          for file in $(git --no-pager diff --name-only --diff-filter=ACMRT "${BASE_SHA}" -- docs/sources); do
+            ./scripts/readability "${file}" "${BASE_SHA}" ${HEAD_SHA} >> .output.txt
           done
+        shell: bash
 
       - uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
         with:

docs/sources/contribute/_index.md

@@ -55,11 +55,11 @@ Small changes might include:
 
 ### Find the source repository
 
+<!-- vale Grafana.Timeless = NO -->
+
 The "latest" and "next" versions of documentation published from public projects have a **{{< translate "docs_feedback_suggest" >}}** link with a pencil icon.
 Click this link to directly edit the page in GitHub.
 
-<!-- vale Grafana.Timeless = NO -->
-
 {{< admonition type="warning" >}}
 Because development happens in the `main` branch on GitHub which generally corresponds to the next version of documentation.
 
@@ -92,15 +92,16 @@ The list of mounts is in the [website repository Hugo configuration file](https:
    GitHub creates a pull request which then goes through the review and approval workflow.
 
 <!-- vale Grafana.Timeless = NO -->
-<!-- vale Grafana.GoogleWill = NO -->
 
 ## Develop a new topic
 
+<!-- vale Grafana.GoogleWill = NO -->
+
 If you want to develop a new topic from scratch, you can create a documentation plan and collaborate with a member of the technical writing team.
 According to the book [_Docs for Developers_](https://docsfordevelopers.com/), a documentation plan is a _flexible outline_ for anticipating where the writing process will lead you.
 
-<!-- vale Grafana.Timeless = YES -->
 <!-- vale Grafana.GoogleWill = YES -->
+<!-- vale Grafana.Timeless = YES -->
 
 Your documentation plan helps you to:
 

scripts/readability

@@ -18,24 +18,16 @@ EOF
 
 function vale_config {
 cat <<EOF
-StylesPath = $(git rev-parse --show-toplevel)/vale
 MinAlertLevel = suggestion
+
 [*.md]
 BasedOnStyles = Grafana
-Grafana.ReadabilityAutomatedReadability = YES
-Grafana.ReadabilityColemanLiau = YES
-Grafana.ReadabilityFleschKincaid = YES
-Grafana.ReadabilityFleschReadingEase = YES
-Grafana.ReadabilityGunningFog = YES
-Grafana.ReadabilityLIX = YES
-Grafana.ReadabilitySMOG = YES
-
-TokenIgnores = (<http[^\n]+>+?), \*\*[^\n]+\*\*, ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \
-(\[.+\]\({{< .+ >}}\)), \
-({{[%<] .+ [%>]}})
 BlockIgnores = (?sm)^({{[%<] [^{]*? [%>]}})\n$, \
 (?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \
 ({{[%<] .+ [%>]}})
+TokenIgnores = (<http[^\n]+>+?), \*\*[^\n]+\*\*, ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \
+(\[.+\]\({{< .+ >}}\)), \
+({{[%<] .+ [%>]}})
 EOF
 }
 
@@ -50,7 +42,7 @@ function readability {
   # docs/sources/_index.md:1:1:Grafana.ReadabilityGunningFog:11.07 (aim for below 10).
   while IFS=' :' read -r _file _line _col rule score rest; do
     printf '%s\t%s\t%s\t%s\n' "${file}" "${rule}" "${score}" "${rest}"
-  done < <(vale --config=<(vale_config) --output=line "${tempfile}")
+  done < <(vale --config=<(vale_config) --filter='.Name matches "Grafana.Readability.*"' --output=line "${tempfile}")
 }
 
 case "${#}" in
@@ -67,8 +59,8 @@ case "${#}" in
   3)
     # Can only compare if the file exists in both revisions.
     if git show "$2:$1" &>/dev/null; then
-      readarray -t before < <(readability "$1" "$2" | grep Readability | sort)
-      readarray -t after < <(readability "$1" "$3" | grep Readability | sort)
+      readarray -t before < <(readability "$1" "$2" | sort)
+      readarray -t after < <(readability "$1" "$3" | sort)
 
       if [[ "${#after[@]}" -ne "${#before[@]}" ]]; then
         echo 'Unexpected mismatch in before and after metrics' >&2 && exit 1
@@ -77,7 +69,9 @@ case "${#}" in
       for ((i = 0; i < "${#before[@]}"; i++)); do
         read -r _file rule before_score guide <<<"${before[$i]}"
         read -r _file _rule after_score _guide <<<"${after[$i]}"
+
         score="$(bc -l <<<"${after_score} - ${before_score}")"
+
         printf '%s\t%s\t%.2f\t(Δ%+.2f)\t%s\n' "$1" "${rule}" "${after_score}" "${score}" "${guide}"
       done
     else