[docs] [revamp] - Beefing up Vale (#23754)

## Summary & Motivation

This PR beefs up our Vale implementation with some custom rules and
vocabularies. The README for this will be updated in a subsequent PR.

## How I Tested These Changes

eyes, local

docs/.vale.ini

@@ -1,28 +1,36 @@
-StylesPath = "vale/styles"
-MinAlertLevel = suggestion
+########################
+#         ABOUT        #
+########################
 
-Packages = Google 
-Vocab = Dagster
+# This file controls the Vale application, specifically what, where, and how it lints.
 
-[*.{md,mdx,rst}]
-BasedOnStyles = Vale, Google, Dagster
+# Vale config reference: https://vale.sh/docs/topics/config
+# INI syntax: https://ini.unknwon.io/docs/intro
 
-; Ignore all :py directives
-IgnorePatterns = (:py:[^`]+`[^`]+`)
+########################
+#    CORE SETTINGS     #
+########################
+
+StylesPath = "vale/styles"
+MinAlertLevel = suggestion
+Vocab = Dagster
 
-; Error on headings that aren't sentence cased.
-Google.Headings = Error
+########################
+#  FORMAT ASSOCIATIONS #
+########################
 
-; Google avoids using will, we don't need to check for this
-Google.Will = NO
-Google.WordList = NO
+[formats]
+mdx = md
 
-; Exclamation is fine
-Google.Exclamation = NO
+########################
+#    FORMAT-SPECIFIC   #
+########################
 
-; Passive is a bit too noisy
-Google.Passive = NO
+[*.{md,mdx,rst}]
+# Rules in this section are enforced in all md, mdx, and rst files
 
+[*.{md,mdx,rst}]
+BasedOnStyles = Dagster, Terms, Vale
 
-[formats]
-mdx = md
+; Ignore all :py directives
+IgnorePatterns = (:py:[^`]+`[^`]+`)

docs/vale/styles/Google/Acronyms.yml → docs/vale/styles/Dagster/acronyms.yml

@@ -17,6 +17,7 @@ exceptions:
   - DEBUG
   - DOM
   - DPI
+  - ETL
   - FAQ
   - GCC
   - GDB
@@ -43,17 +44,21 @@ exceptions:
   - POST
   - RAM
   - REPL
+  - REST
   - RSA
   - SCM
   - SCSS
+  - SDA
   - SDK
+  - SFTP
   - SQL
   - SSH
   - SSL
   - SVG
   - TBD
   - TCP
   - TODO
+  - UI
   - URI
   - URL
   - USB

docs/vale/styles/Dagster/eol-whitespace.yml → docs/vale/styles/Dagster/chars-eol-whitespace.yml

@@ -1,4 +1,3 @@
----
 extends: existence
 message: "Remove whitespace characters from the end of the line."
 link: https://docs.gitlab.com/ee/development/documentation/versions.html

docs/vale/styles/Google/Colons.yml → docs/vale/styles/Dagster/colons.yml

@@ -1,8 +1,10 @@
+## This rule finds capitalized words immediately following a colon (:)
+
 extends: existence
 message: "'%s' should be in lowercase."
 link: 'https://developers.google.com/style/colons'
 nonword: true
 level: warning
 scope: sentence
 tokens:
-  - ':\s[A-Z]'
+  - ':\s[A-Z]'

docs/vale/styles/Google/Contractions.yml → docs/vale/styles/Dagster/contractions.yml

@@ -27,4 +27,4 @@ swap:
   what is: what's
   when is: when's
   where is: where's
-  will not: won't
+  will not: won't

docs/vale/styles/Google/EmDash.yml → docs/vale/styles/Dagster/dashes.yml

@@ -9,5 +9,4 @@ action:
     - trim
     - " "
 tokens:
-  - '\s[—–]\s'
-
+  - '\s[—–]\s'

docs/vale/styles/Dagster/gender.yml

@@ -0,0 +1,14 @@
+extends: existence
+message: "Use a gender-neutral pronoun instead of '%s'."
+link: "https://github.com/DataDog/documentation/blob/master/CONTRIBUTING.md#gender"
+level: error
+ignorecase: true
+tokens:
+  - he/she
+  - s/he
+  - \(s\)he
+  - \bhe\b
+  - \bhim\b
+  - \bhis\b
+  - \bshe\b
+  - \bher\b

docs/vale/styles/Dagster/heading-characters.yml

@@ -0,0 +1,11 @@
+## This rule finds non-allowed characters in headings
+## WHY? Headings don't need periods or formatting, ex: `@asset`
+
+extends: existence
+message: "Headings shouldn't have periods or other Markdown formatting"
+level: error
+scope: heading
+ignorecase: false
+nonword: true
+raw:
+  - '`|(?<=.)\.$'

docs/vale/styles/Dagster/heading-content.yml

@@ -6,5 +6,4 @@ ignorecase: true
 nonword: true
 scope: raw
 tokens:
-  - '\#+ How it works'
   - '\#+ Overview'

docs/vale/styles/Dagster/headings-casing.yml

@@ -0,0 +1,8 @@
+## This rule finds section headings that don't use sentence casing.
+## Ex: This is correct, but This Is Not Correct
+
+extends: capitalization
+message: "'%s' should be in sentence case"
+level: error
+scope: heading
+match: $sentence

docs/vale/styles/Dagster/section-heading-gerund.yml → docs/vale/styles/Dagster/headings-gerund.yml

@@ -1,3 +1,6 @@
+## This rule flags gerunds (ex: "Linting" versus "Lint") in section headings
+## WHY? Gerunds don't always translate well into other languages
+
 extends: existence
 message: Section '%v' should not start with a gerund (verb ending in "ing")
 level: error

docs/vale/styles/Dagster/link-text.yml

@@ -0,0 +1,26 @@
+## This rule flags vague language in links. Links should tell the user where you're sending them.
+
+extends: substitution
+message: "Avoid vague text in links like '%s' unless you can pair it with more descriptive text."
+link: 'https://github.com/DataDog/documentation/blob/master/CONTRIBUTING.md#links'
+ignorecase: true
+scope: raw
+nonword: true
+level: warning
+
+swap:
+# For the word 'here' in Markdown and HTML links
+  '\[here\]\(.*?\)': 'here'
+  '<a\s*href\s*=\s*".*?".*?>\s*here\s*</a>': 'here'
+
+# For the word 'this' in Markdown and HTML links
+  '\[this\]\(.*?\)': 'this'
+  '<a\s*href\s*=\s*".*?".*?>\s*this\s*</a>': 'this'
+
+# For the word 'page' in Markdown and HTML links
+  '\[page\]\(.*?\)': 'page'
+  '<a\s*href\s*=\s*".*?".*?>\s*page\s*</a>': 'page'
+
+# For the phrase 'this page' in Markdown and HTML links
+  '\[this page\]\(.*?\)': 'this page'
+  '<a\s*href\s*=\s*".*?".*?>\s*this page\s*</a>': 'this page'

docs/vale/styles/Dagster/missing-tos.yml

@@ -0,0 +1,9 @@
+## This rule finds missing instances of 'to'. Ex: It would be great // // write a story.
+
+extends: sequence
+message: "Missing 'to': Did you mean '%[2]s %[3]s *to* %[4]s'?"
+tokens:
+  - tag: MD
+  - pattern: be
+  - tag: JJ
+  - tag: VB|VBN

docs/vale/styles/Google/OptionalPlurals.yml → docs/vale/styles/Dagster/optional-plurals.yaml

@@ -1,3 +1,5 @@
+## This rule finds optional plurals in parentheses. Ex: 'The tag(s)'' instead of 'The tag or tags'
+
 extends: existence
 message: "Don't use plurals in parentheses such as in '%s'."
 link: "https://developers.google.com/style/plurals-parentheses"
@@ -9,4 +11,4 @@ action:
     - trim_right
     - "(s)"
 tokens:
-  - '\b\w+\(s\)'
+  - '\b\w+\(s\)'

docs/vale/styles/Google/OxfordComma.yml → docs/vale/styles/Dagster/oxford.yml

@@ -4,4 +4,4 @@ link: 'https://developers.google.com/style/commas'
 scope: sentence
 level: warning
 tokens:
-  - '(?:[^,]+,){1,}\s\w+\s(?:and|or)'
+  - '(?:[^,]+,){1,}\s\w+\s(?:and|or)'

docs/vale/styles/Google/Quotes.yml → docs/vale/styles/Dagster/quotes-punctuation.yaml

@@ -1,7 +1,7 @@
 extends: existence
-message: "Commas and periods go inside quotation marks."
+message: "Commas, exclamation points, and periods go inside quotation marks."
 link: 'https://developers.google.com/style/quotation-marks'
 level: error
 nonword: true
 tokens:
-  - '"[^"]+"[.,?]'
+  - '"[^"]+"[.,?]'

docs/vale/styles/Dagster/readability.yml

@@ -0,0 +1,8 @@
+extends: metric
+message: "Try to keep the Automated Readability Index (%s) below 8."
+link: https://en.wikipedia.org/wiki/Automated_readability_index
+
+formula: |
+  (4.71 * (characters / words)) + (0.5 * (words / sentences)) - 21.43
+
+condition: "> 8"

docs/vale/styles/Dagster/repeated-words.yml

@@ -0,0 +1,8 @@
+## This rule catches instances of repeated words. Ex: This //is is// a sentence.
+
+extends: repetition
+message: "'%s' is repeated!"
+level: error
+alpha: true
+tokens:
+  - '[^\s]+'

docs/vale/styles/Dagster/sentence-length-variety.yml

@@ -0,0 +1,45 @@
+extends: script
+message: "This paragraph has a stdev less than 2"
+link: https://tengolang.com/
+scope: paragraph
+script: |
+  text := import("text")
+  math := import("math")
+
+  matches := []
+
+  each := func(seq, fn) {
+    for x in seq {
+        fn(x)
+    }
+  }
+
+  sum := func(seq) {
+    s := 0
+    each(seq, func(x) {
+      s += x
+    })
+    return s
+  }
+
+  stdev := func(seq) {
+    size := len(seq)
+    mean := sum(seq) / size
+
+    sd := 0.0
+    each(seq, func(x) {
+      sd += math.pow(x - mean, 2)
+    })
+
+    return math.sqrt(sd / size)
+  }
+
+  lengths := []
+  for sent in text.re_split(`[.!?] `, scope, -1) {
+    lengths = append(lengths, len(text.fields(sent)))
+  }
+
+  computed := stdev(lengths)
+  if computed < 2 && len(lengths) >= 3 {
+    matches = append(matches, {begin: 0, end: len(scope)})
+  }

docs/vale/styles/Dagster/spacing.yaml

@@ -0,0 +1,10 @@
+extends: existence
+message: "Use only one space between words and sentences (not two)."
+link: 'https://developers.google.com/style/sentence-spacing'
+level: error
+nonword: true
+action:
+  name: remove
+tokens:
+  - '[a-z][.?!] {2,}[A-Z]'
+  - '[a-z][.?!][A-Z]'

docs/vale/styles/Dagster/spelling.yml

@@ -0,0 +1,6 @@
+# Uses the built-in dictionary and filters.
+extends: spelling
+message: "Is '%s' spelled correctly?"
+level: error
+ignore:
+  - ignore.txt

docs/vale/styles/Dagster/todos.yml

@@ -0,0 +1,11 @@
+# This rule will flag "TODO" or "todo" unless they occur inside HTML comments.
+
+extends: existence
+message: "Remove or comment out TODOs."
+level: error
+scope: text
+ignorecase: true
+tokens: 
+  - '\b[Tt][Oo][Dd][Oo]\b'
+exceptions: 
+  - '<!--.*?\b[Tt][Oo][Dd][Oo]\b.*?-->'