Refactor Grafana Vale style so it can be easily packaged

.github/workflows/validate-documentation.yml

@@ -73,11 +73,19 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+      - name: Sync packages
+        run: vale sync
       - name: Run linter
         run: >
-          /bin/reviewdog
-          --conf=/etc/vale/.reviewdog.yml
+          vale
+          '--glob=*.md'
+          --minAlertLevel=warning
+          --output=/etc/vale/rdjsonl.tmpl
+          docs/sources
+          | reviewdog
+          -f=rdjsonl
           --fail-on-error
+          --name=vale
           --reporter=github-pr-review
         env:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -5,4 +5,5 @@
 /add-to-docs-project/node_modules/
 /add-to-docs-project/index.mjs
 build.conf
-/dist
+/dist
+/vale/Grafana.zip

.vale.ini

@@ -1,6 +1,4 @@
 MinAlertLevel = suggestion
-Packages = Google, https://github.com/errata-ai/Hugo/releases/download/v0.2.0/Hugo.zip, Readability
-StylesPath = vale
+Packages = Google, https://github.com/errata-ai/Hugo/releases/download/v0.2.0/Hugo.zip, Readability, vale/Grafana
 [*]
 BasedOnStyles = Grafana
-TokenIgnores = (<http[^\n]+>+?), \*\*[^\n]+\*\*

RELEASE.md

@@ -46,3 +46,19 @@ The major version tag should point to the same commit as the latest major and mi
 The major and minor version tag should point to the same commit as the major, minor, and patch version tag.
 
 The `--force` flag provided to the `git tag` command overwrites existing tags which you need to be able to move the major version and major and minor version tags when you release a new major, minor, and patch version.
+
+## Vale package
+
+To release a new version of the Writers' Toolkit Vale package:
+
+1. Create a new tag for the release with the form `vale/<VERSION>`.
+
+   The Vale package follows [semantic versioning](https://semver.org).
+
+1. Using the checked out tag, create an archive of the [Vale package directory](./vale/Grafana).
+
+   ```console
+   cd vale && make Grafana.zip
+   ```
+
+1. Create a GitHub release and upload the [`vale/Grafana.zip`](./vale/Grafana.zip) archive.

docs/make-docs

@@ -6,6 +6,14 @@
 # [Semantic versioning](https://semver.org/) is used to help the reader identify the significance of changes.
 # Changes are relevant to this script and the support docs.mk GNU Make interface.
 #
+# ## 8.3.0 (2024-12-27)
+#
+# ### Added
+#
+# - Debug output of the final command when DEBUG=true.
+#
+#   Useful to inspect if the script is correctly constructing the final command.
+#
 # ## 8.2.0 (2024-12-22)
 #
 # ### Removed
@@ -631,7 +639,7 @@ POSIX_HERESTRING
 
     case "${_project}" in
       # Workaround for arbitrary mounts where the version field is expected to be the local directory
-      # and the repo field is expected to be the container directory.
+     # and the repo field is expected to be the container directory.
       arbitrary)
         echo "${_project}^${_version}^${_repo}^" # TODO
         ;;
@@ -801,6 +809,10 @@ case "${image}" in
                 | sed "s#$(proj_dst "${proj}")#sources#"
 EOF
 
+    if [ -n "${DEBUG}" ]; then
+      debg "${cmd}"
+    fi
+
     case "${OUTPUT_FORMAT}" in
       human)
         if ! command -v jq >/dev/null 2>&1; then
@@ -837,6 +849,10 @@ EOF
                 /hugo/content/docs
 EOF
 
+    if [ -n "${DEBUG}" ]; then
+      debg "${cmd}"
+    fi
+
     case "${OUTPUT_FORMAT}" in
       human)
         ${cmd} --output=line \

docs/sources/review/lint-prose/rules.md

@@ -2,7 +2,7 @@
 date: "2024-06-25"
 description: A description of every Grafana Labs prose linting rule.
 menuTitle: Rules
-review_date: "2024-09-19"
+review_date: "2024-12-16"
 title: Vale rules
 ---
 
@@ -102,8 +102,8 @@ Use 'AM' or 'PM' (preceded by a space).
 
 _`<CURRENT TEXT>`_ was matched by one or more of the following regular expressions:
 
-- `\d{1,2}[AP]M`
-- `\d{1,2} ?[ap]m`
+- `\d{1,2}[AP]M\b`
+- `\d{1,2} ?[ap]m\b`
 - `\d{1,2} ?[aApP]\.[mM]\.`
 
 [More information ->](https://developers.google.com/style/word-list)
@@ -165,47 +165,43 @@ Extends: substitution
 
 Consider using _`<REPLACEMENT TEXT>`_ instead of _`<CURRENT TEXT>`_.
 
-| Current text                   | Replacement text              |
-| ------------------------------ | ----------------------------- |
-| `(?:alumnae\|alumni)`          | `graduates`                   |
-| `(?:alumna\|alumnus)`          | `graduate`                    |
-| `air(?:m[ae]n\|wom[ae]n)`      | `pilot(s)`                    |
-| `anchor(?:m[ae]n\|wom[ae]n)`   | `anchor(s)`                   |
-| `authoress`                    | `author`                      |
-| `camera(?:m[ae]n\|wom[ae]n)`   | `camera operator(s)`          |
-| `chair(?:m[ae]n\|wom[ae]n)`    | `chair(s)`                    |
-| `congress(?:m[ae]n\|wom[ae]n)` | `member(s) of congress`       |
-| `door(?:m[ae]\|wom[ae]n)`      | `concierge(s)`                |
-| `draft(?:m[ae]n\|wom[ae]n)`    | `drafter(s)`                  |
-| `fire(?:m[ae]n\|wom[ae]n)`     | `firefighter(s)`              |
-| `fisher(?:m[ae]n\|wom[ae]n)`   | `fisher(s)`                   |
-| `fresh(?:m[ae]n\|wom[ae]n)`    | `first-year student(s)`       |
-| `garbage(?:m[ae]n\|wom[ae]n)`  | `waste collector(s)`          |
-| `lady lawyer`                  | `lawyer`                      |
-| `ladylike`                     | `courteous`                   |
-| `landlord`                     | `building manager`            |
-| `mail(?:m[ae]n\|wom[ae]n)`     | `mail carriers`               |
-| `man and wife`                 | `husband and wife`            |
-| `man enough`                   | `strong enough`               |
-| `mankind`                      | `human kind`                  |
-| `manmade`                      | `manufactured`                |
-| `manpower`                     | `personnel`                   |
-| `men and girls`                | `men and women`               |
-| `middle(?:m[ae]n\|wom[ae]n)`   | `intermediary`                |
-| `news(?:m[ae]n\|wom[ae]n)`     | `journalist(s)`               |
-| `ombuds(?:man\|woman)`         | `ombuds`                      |
-| `oneupmanship`                 | `upstaging`                   |
-| `poetess`                      | `poet`                        |
-| `police(?:m[ae]n\|wom[ae]n)`   | `police officer(s)`           |
-| `repair(?:m[ae]n\|wom[ae]n)`   | `technician(s)`               |
-| `sales(?:m[ae]n\|wom[ae]n)`    | `salesperson or sales people` |
-| `service(?:m[ae]n\|wom[ae]n)`  | `soldier(s)`                  |
-| `steward(?:ess)?`              | `flight attendant`            |
-| `tribes(?:m[ae]n\|wom[ae]n)`   | `tribe member(s)`             |
-| `waitress`                     | `waiter`                      |
-| `woman doctor`                 | `doctor`                      |
-| `woman scientist[s]?`          | `scientist(s)`                |
-| `work(?:m[ae]n\|wom[ae]n)`     | `worker(s)`                   |
+| Current text                  | Replacement text              |
+| ----------------------------- | ----------------------------- |
+| `(?:alumnae\|alumni)`         | `graduates`                   |
+| `(?:alumna\|alumnus)`         | `graduate`                    |
+| `air(?:m[ae]n\|wom[ae]n)`     | `pilot(s)`                    |
+| `anchor(?:m[ae]n\|wom[ae]n)`  | `anchor(s)`                   |
+| `authoress`                   | `author`                      |
+| `camera(?:m[ae]n\|wom[ae]n)`  | `camera operator(s)`          |
+| `door(?:m[ae]\|wom[ae]n)`     | `concierge(s)`                |
+| `draft(?:m[ae]n\|wom[ae]n)`   | `drafter(s)`                  |
+| `fire(?:m[ae]n\|wom[ae]n)`    | `firefighter(s)`              |
+| `fisher(?:m[ae]n\|wom[ae]n)`  | `fisher(s)`                   |
+| `fresh(?:m[ae]n\|wom[ae]n)`   | `first-year student(s)`       |
+| `garbage(?:m[ae]n\|wom[ae]n)` | `waste collector(s)`          |
+| `lady lawyer`                 | `lawyer`                      |
+| `ladylike`                    | `courteous`                   |
+| `mail(?:m[ae]n\|wom[ae]n)`    | `mail carriers`               |
+| `man and wife`                | `husband and wife`            |
+| `man enough`                  | `strong enough`               |
+| `mankind`                     | `human kind\|humanity`        |
+| `manmade`                     | `manufactured`                |
+| `manpower`                    | `personnel`                   |
+| `middle(?:m[ae]n\|wom[ae]n)`  | `intermediary`                |
+| `news(?:m[ae]n\|wom[ae]n)`    | `journalist(s)`               |
+| `ombuds(?:man\|woman)`        | `ombuds`                      |
+| `oneupmanship`                | `upstaging`                   |
+| `poetess`                     | `poet`                        |
+| `police(?:m[ae]n\|wom[ae]n)`  | `police officer(s)`           |
+| `repair(?:m[ae]n\|wom[ae]n)`  | `technician(s)`               |
+| `sales(?:m[ae]n\|wom[ae]n)`   | `salesperson or sales people` |
+| `service(?:m[ae]n\|wom[ae]n)` | `soldier(s)`                  |
+| `steward(?:ess)?`             | `flight attendant`            |
+| `tribes(?:m[ae]n\|wom[ae]n)`  | `tribe member(s)`             |
+| `waitress`                    | `waiter`                      |
+| `woman doctor`                | `doctor`                      |
+| `woman scientist[s]?`         | `scientist(s)`                |
+| `work(?:m[ae]n\|wom[ae]n)`    | `worker(s)`                   |
 
 [More information ->](https://developers.google.com/style/inclusive-documentation)
 
@@ -217,7 +213,7 @@ _`<CURRENT TEXT>`_ doesn't need a hyphen.
 
 _`<CURRENT TEXT>`_ was matched by one or more of the following regular expressions:
 
-- `\s[^\s-]+ly-`
+- `\b[^\s-]+ly-\w+\b`
 
 [More information ->](https://developers.google.com/style/hyphens)
 
@@ -666,10 +662,10 @@ Extends: capitalization
 
 Use sentence-style capitalization for _`<CURRENT TEXT>`_.
 
-If your heading contains capitalized words that represent product names, you need to add those words as exceptions in https://github.com/grafana/writers-toolkit/blob/main/vale/Grafana/Headings.yml for them to be considered correctly cased.
-
 Vale considers multi-word exceptions such as _Grafana Enterprise Metrics_ as a single correctly cased word.
 
+If your heading contains capitalized words that represent product names, you need to add those words to the Grafana dictionary or the list of static exceptions in https://github.com/grafana/writers-toolkit/blob/main/vale/Headings.jsonnet for them to be considered correctly cased.
+
 [More information ->](https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings)
 
 ### Grafana.Kubernetes

vale/.vale.ini

@@ -1,6 +1,5 @@
 MinAlertLevel = suggestion
-Packages = Google, https://github.com/errata-ai/Hugo/releases/download/v0.2.0/Hugo.zip, Readability
-StylesPath = /etc/vale/styles
+Packages = Grafana
+
 [*]
 BasedOnStyles = Grafana
-TokenIgnores = (<http[^\n]+>+?), \*\*[^\n]+\*\*

vale/Dockerfile

@@ -21,23 +21,17 @@ RUN mv reviewdog /out
 ################################################################################
 FROM jdkato/vale:v3.8.0
 
-ENV DICPATH=/etc/vale/dictionaries
+COPY --from=reviewdog /out/reviewdog /bin
+
+# Git is useful for reporting with reviewdog.
+RUN apk add --no-cache git
 
 RUN mkdir -p /etc/vale
+WORKDIR /etc/vale
 
-COPY Google /etc/vale/styles/Google
-COPY Grafana /etc/vale/styles/Grafana
+COPY .reviewdog.yml /etc/vale/.reviewdog.yml
 COPY .vale.ini /etc/vale/.vale.ini
-COPY .vale-config /etc/vale/.vale-config
-COPY config /etc/vale/styles/config
-COPY dictionaries /etc/vale/dictionaries
+COPY Grafana /etc/vale/Grafana
 COPY rdjsonl.tmpl /etc/vale/rdjsonl.tmpl
-COPY .reviewdog.yml /etc/vale/.reviewdog.yml
 
-# Git is useful for reporting with reviewdog.
-RUN apk add --no-cache git
-
-COPY --from=reviewdog /out/reviewdog /bin
-
-WORKDIR /etc/vale
 RUN vale sync

vale/Google/AMPM.yml

@@ -4,6 +4,6 @@ link: "https://developers.google.com/style/word-list"
 level: error
 nonword: true
 tokens:
-  - '\d{1,2}[AP]M'
-  - '\d{1,2} ?[ap]m'
+  - '\d{1,2}[AP]M\b'
+  - '\d{1,2} ?[ap]m\b'
   - '\d{1,2} ?[aApP]\.[mM]\.'

vale/Google/EmDash.yml

@@ -6,7 +6,7 @@ level: error
 action:
   name: edit
   params:
-    - remove
+    - trim
     - " "
 tokens:
   - '\s[—–]\s'

vale/Google/Exclamation.yml

@@ -4,6 +4,9 @@ link: "https://developers.google.com/style/exclamation-points"
 nonword: true
 level: error
 action:
-  name: remove
+  name: edit
+  params:
+    - trim_right
+    - "!"
 tokens:
   - '\w+!(?:\s|$)'

vale/Google/GenderBias.yml

@@ -1,7 +1,7 @@
 extends: substitution
 message: "Consider using '%s' instead of '%s'."
-link: "https://developers.google.com/style/inclusive-documentation"
 ignorecase: true
+link: "https://developers.google.com/style/inclusive-documentation"
 level: error
 action:
   name: replace
@@ -12,8 +12,6 @@ swap:
   anchor(?:m[ae]n|wom[ae]n): anchor(s)
   authoress: author
   camera(?:m[ae]n|wom[ae]n): camera operator(s)
-  chair(?:m[ae]n|wom[ae]n): chair(s)
-  congress(?:m[ae]n|wom[ae]n): member(s) of congress
   door(?:m[ae]|wom[ae]n): concierge(s)
   draft(?:m[ae]n|wom[ae]n): drafter(s)
   fire(?:m[ae]n|wom[ae]n): firefighter(s)
@@ -22,14 +20,12 @@ swap:
   garbage(?:m[ae]n|wom[ae]n): waste collector(s)
   lady lawyer: lawyer
   ladylike: courteous
-  landlord: building manager
   mail(?:m[ae]n|wom[ae]n): mail carriers
   man and wife: husband and wife
   man enough: strong enough
-  mankind: human kind
+  mankind: human kind|humanity
   manmade: manufactured
   manpower: personnel
-  men and girls: men and women
   middle(?:m[ae]n|wom[ae]n): intermediary
   news(?:m[ae]n|wom[ae]n): journalist(s)
   ombuds(?:man|woman): ombuds

vale/Google/HeadingPunctuation.yml

@@ -7,7 +7,7 @@ scope: heading
 action:
   name: edit
   params:
-    - remove
+    - trim_right
     - "."
 tokens:
   - '[a-z0-9][.]\s*$'

vale/Google/Headings.yml

@@ -26,3 +26,4 @@ exceptions:
   - Visual
   - VS
   - Windows
+  - JSON

vale/Google/LyHyphens.yml

@@ -7,8 +7,8 @@ nonword: true
 action:
   name: edit
   params:
-    - replace
+    - regex
     - "-"
     - " "
 tokens:
-  - '\s[^\s-]+ly-'
+  - '\b[^\s-]+ly-\w+\b'

vale/Google/OptionalPlurals.yml

@@ -6,7 +6,7 @@ nonword: true
 action:
   name: edit
   params:
-    - remove
+    - trim_right
     - "(s)"
 tokens:
   - '\b\w+\(s\)'

vale/Google/WordList.yml

@@ -38,7 +38,6 @@ swap:
   cellular network: mobile network
   chapter: documents|pages|sections
   check box: checkbox
-  check: select
   CLI: command-line tool
   click on: click|click in
   Cloud: Google Cloud Platform|GCP

vale/Grafana/.vale.ini

@@ -0,0 +1,5 @@
+Packages = Google, https://github.com/errata-ai/Hugo/releases/download/v0.2.0/Hugo.zip
+
+[*]
+BasedOnStyles = Grafana
+TokenIgnores = (<http[^\n]+>+?), \*\*[^\n]+\*\*