diff --git a/.github/workflows/docs-website-vale.yml b/.github/workflows/docs-website-vale.yml index 43e678b941..89b4d8fb37 100644 --- a/.github/workflows/docs-website-vale.yml +++ b/.github/workflows/docs-website-vale.yml @@ -32,9 +32,8 @@ jobs: - name: Vale uses: errata-ai/vale-action@v2 with: - files: | - docs-website/docs - docs-website/versioned_docs + vale_flags: "--config=docs-website/.vale.ini" + files: docs-website/docs reporter: github-pr-review fail_on_error: false env: diff --git a/docs-website/.vale.ini b/docs-website/.vale.ini index ed71526f60..e615d9ece8 100644 --- a/docs-website/.vale.ini +++ b/docs-website/.vale.ini @@ -5,3 +5,17 @@ MinAlertLevel = suggestion [*.{md,mdx}] BasedOnStyles = Vale, Google, MyStyle + +# Disable Vale's built-in spell checker (flags technical terms like "embedders") +Vale.Spelling = NO + +# Disable Google.Headings - conflicts with MyStyle.Headings (title case vs sentence case) +# and doesn't handle PascalCase component names well +Google.Headings = NO + +# Disable Google.Passive - too noisy for technical documentation where passive voice +# is often appropriate and hard to rephrase +Google.Passive = NO + +# Disable Google.Acronyms - AI/ML acronyms like RAG, LLM are well-known to our audience +Google.Acronyms = NO diff --git a/docs-website/.vale/styles/Google/Latin.yml b/docs-website/.vale/styles/Google/Latin.yml index d91700de3f..d64c184db4 100644 --- a/docs-website/.vale/styles/Google/Latin.yml +++ b/docs-website/.vale/styles/Google/Latin.yml @@ -9,3 +9,5 @@ action: swap: '\b(?:eg|e\.g\.)[\s,]': for example '\b(?:ie|i\.e\.)[\s,]': that is + '\betc\.': and so on + '\bvs\.': versus diff --git a/docs-website/.vale/styles/MyStyle/Abbreviations.yml b/docs-website/.vale/styles/MyStyle/Abbreviations.yml new file mode 100644 index 0000000000..795b6397d6 --- /dev/null +++ b/docs-website/.vale/styles/MyStyle/Abbreviations.yml @@ -0,0 +1,9 @@ +extends: substitution +message: "Use '%s' instead of the abbreviation '%s'." +level: warning +ignorecase: true +action: + name: replace +swap: + '\bmisc\b': miscellaneous + '\bdoc\b': document diff --git a/docs-website/.vale/styles/MyStyle/AvoidJust.yml b/docs-website/.vale/styles/MyStyle/AvoidJust.yml deleted file mode 100644 index a4b028e58c..0000000000 --- a/docs-website/.vale/styles/MyStyle/AvoidJust.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "'just' is often unnecessary. Consider removing it for clarity." -level: suggestion -nonword: true -scope: text -tokens: - - just diff --git a/docs-website/.vale/styles/MyStyle/AvoidPlease.yml b/docs-website/.vale/styles/MyStyle/AvoidPlease.yml new file mode 100644 index 0000000000..1d207b0bd5 --- /dev/null +++ b/docs-website/.vale/styles/MyStyle/AvoidPlease.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Avoid 'please' in instructions—it can make actions seem optional. Use imperative instead." +level: warning +ignorecase: true +scope: text +tokens: + - please diff --git a/docs-website/.vale/styles/MyStyle/AvoidThirdPerson.yml b/docs-website/.vale/styles/MyStyle/AvoidThirdPerson.yml index 241a4665b5..e8b411b81e 100644 --- a/docs-website/.vale/styles/MyStyle/AvoidThirdPerson.yml +++ b/docs-website/.vale/styles/MyStyle/AvoidThirdPerson.yml @@ -1,14 +1,13 @@ extends: existence -message: "Prefer second person (e.g., 'you') instead of '%s'." +message: "Prefer second person ('you') instead of '%s'." level: warning -nonword: true scope: text tokens: - the user - the customer - the client - - he - - she - - his - - her + - '\bhe\b' + - '\bshe\b' + - '\bhis\b' + - '\bher\b' - their system diff --git a/docs-website/.vale/styles/MyStyle/Branding.yml b/docs-website/.vale/styles/MyStyle/Branding.yml index 1928f0ec2b..a210c9874a 100644 --- a/docs-website/.vale/styles/MyStyle/Branding.yml +++ b/docs-website/.vale/styles/MyStyle/Branding.yml @@ -1,12 +1,11 @@ extends: substitution message: "'%s' is not the correct branding. Use '%s' instead." level: error -ignorecase: true +ignorecase: false swap: Deepset: deepset + DEEPSET: deepset Huggingface: Hugging Face huggingface: Hugging Face HuggingFace: Hugging Face - Haystack: Haystack # Pass-through to suppress errors from wrong variants - haystack: Haystack - Deepset Platform: deepset AI Platform + HAYSTACK: Haystack diff --git a/docs-website/.vale/styles/MyStyle/FileExtensions.yml b/docs-website/.vale/styles/MyStyle/FileExtensions.yml index 2ecf250316..6e34dbc192 100644 --- a/docs-website/.vale/styles/MyStyle/FileExtensions.yml +++ b/docs-website/.vale/styles/MyStyle/FileExtensions.yml @@ -1,5 +1,5 @@ extends: substitution -message: "Use uppercase for file extensions (e.g., '%s' → '%s')." +message: "Use uppercase for file extensions: '%s' → '%s'." level: warning ignorecase: false swap: diff --git a/docs-website/.vale/styles/MyStyle/GUITerms.yml b/docs-website/.vale/styles/MyStyle/GUITerms.yml new file mode 100644 index 0000000000..75ccbca9c9 --- /dev/null +++ b/docs-website/.vale/styles/MyStyle/GUITerms.yml @@ -0,0 +1,25 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +level: warning +ignorecase: true +action: + name: replace +swap: + drop-down list: list + drop-down: list + dropdown: list + radio button: option + radio buttons: options + text field: field + text fields: fields + text area: field + hyperlink: link + hyperlinks: links + pop-up menu: context menu + popup menu: context menu + push button: button + push buttons: buttons + list box: list + choice box: list + pull-down list: list + scroll bar: scroll diff --git a/docs-website/.vale/styles/MyStyle/Headings.yml b/docs-website/.vale/styles/MyStyle/Headings.yml index 6abe1b2a8a..8840d1d5ab 100644 --- a/docs-website/.vale/styles/MyStyle/Headings.yml +++ b/docs-website/.vale/styles/MyStyle/Headings.yml @@ -1,5 +1,5 @@ extends: capitalization -message: "Headings and titles should use title case (e.g., 'Create a Workspace in deepset Cloud')." +message: "Headings and titles should use title case." level: warning scope: heading style: AP diff --git a/docs-website/.vale/styles/MyStyle/KeyboardKeys.yml b/docs-website/.vale/styles/MyStyle/KeyboardKeys.yml index 1686014ad0..f1bdcd2ce4 100644 --- a/docs-website/.vale/styles/MyStyle/KeyboardKeys.yml +++ b/docs-website/.vale/styles/MyStyle/KeyboardKeys.yml @@ -1,5 +1,5 @@ extends: existence -message: "Keyboard keys should be capitalized (e.g., 'Delete', 'F2')." +message: "Keyboard keys should be capitalized ('Delete', 'Enter', 'F2')." level: warning scope: text tokens: diff --git a/docs-website/.vale/styles/MyStyle/Numbers.yml b/docs-website/.vale/styles/MyStyle/Numbers.yml index a9e4a0d3a2..aedad388d0 100644 --- a/docs-website/.vale/styles/MyStyle/Numbers.yml +++ b/docs-website/.vale/styles/MyStyle/Numbers.yml @@ -1,15 +1,7 @@ extends: existence -message: "Spell out numbers zero through nine unless part of time, measurement, or list." -level: warning +message: "Consider spelling out numbers zero through nine (exceptions: time, measurements, lists with larger numbers)." +level: suggestion scope: text nonword: true tokens: - - 1 - - 2 - - 3 - - 4 - - 5 - - 6 - - 7 - - 8 - - 9 + - '\b[1-9]\b' diff --git a/docs-website/.vale/styles/MyStyle/ParameterFormatting.yml b/docs-website/.vale/styles/MyStyle/ParameterFormatting.yml index d321203fad..738bb7f7ac 100644 --- a/docs-website/.vale/styles/MyStyle/ParameterFormatting.yml +++ b/docs-website/.vale/styles/MyStyle/ParameterFormatting.yml @@ -1,8 +1,8 @@ extends: existence message: "Wrap parameter, class, or method names like '%s' in backticks." -level: warning +level: suggestion scope: text raw: - - '\b[a-zA-Z_][a-zA-Z0-9_]*\(\)' # Methods like pipeline() - - '\b[A-Z][a-zA-Z0-9]*\b' # Class names like MyClass + - '\b[a-zA-Z_][a-zA-Z0-9_]*\(\)' # Methods like pipeline(), run() + - '\b[a-z]+_[a-z_]+\b' # snake_case like max_length - '\b[a-z]+[A-Z][a-zA-Z0-9]*\b' # camelCase like maxDepth diff --git a/docs-website/.vale/styles/MyStyle/PassiveVoice.yml b/docs-website/.vale/styles/MyStyle/PassiveVoice.yml deleted file mode 100644 index 44a246e6d6..0000000000 --- a/docs-website/.vale/styles/MyStyle/PassiveVoice.yml +++ /dev/null @@ -1,9 +0,0 @@ -extends: existence -message: "Rephrase passive or indirect constructions like '%s' to be more active and direct." -level: suggestion -nonword: true -scope: text -tokens: - - allows you to - - enables you to - - is used to diff --git a/docs-website/.vale/styles/MyStyle/QuestionAnswering.yml b/docs-website/.vale/styles/MyStyle/QuestionAnswering.yml new file mode 100644 index 0000000000..7bf9ce3b5e --- /dev/null +++ b/docs-website/.vale/styles/MyStyle/QuestionAnswering.yml @@ -0,0 +1,9 @@ +extends: substitution +message: "Write '%s' without a hyphen: '%s'." +level: warning +ignorecase: true +action: + name: replace +swap: + question-answering: question answering + document-retrieval: document retrieval diff --git a/docs-website/.vale/styles/MyStyle/TheFollowing.yml b/docs-website/.vale/styles/MyStyle/TheFollowing.yml new file mode 100644 index 0000000000..73b33a5750 --- /dev/null +++ b/docs-website/.vale/styles/MyStyle/TheFollowing.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Avoid '%s'—it's implied by the colon. Rephrase or remove." +level: suggestion +ignorecase: true +scope: text +tokens: + - the following + - as follows diff --git a/docs-website/.vale/styles/MyStyle/WeakWords.yml b/docs-website/.vale/styles/MyStyle/WeakWords.yml index b750e67a1d..bf3c124e4d 100644 --- a/docs-website/.vale/styles/MyStyle/WeakWords.yml +++ b/docs-website/.vale/styles/MyStyle/WeakWords.yml @@ -8,3 +8,7 @@ tokens: - simply - basically - leverage + - very + - really + - extremely + - quite diff --git a/docs-website/.vale/styles/MyStyle/WordChoice.yml b/docs-website/.vale/styles/MyStyle/WordChoice.yml new file mode 100644 index 0000000000..17aa7dbbb5 --- /dev/null +++ b/docs-website/.vale/styles/MyStyle/WordChoice.yml @@ -0,0 +1,24 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +level: warning +ignorecase: true +action: + name: replace +swap: + utilize: use + utilizes: uses + utilizing: using + utilized: used + purchase: buy + purchases: buys + purchasing: buying + purchased: bought + assist: help + assists: helps + assisting: helping + assisted: helped + info: information + leverage: use + leverages: uses + leveraging: using + leveraged: used