diff options
Diffstat (limited to 'doc/.vale')
| -rw-r--r-- | doc/.vale/gitlab/Acronyms.yml | 16 | ||||
| -rw-r--r-- | doc/.vale/gitlab/Admin.yml | 2 | ||||
| -rw-r--r-- | doc/.vale/gitlab/AlertBoxCaution.yml | 14 | ||||
| -rw-r--r-- | doc/.vale/gitlab/AlertBoxDanger.yml | 14 | ||||
| -rw-r--r-- | doc/.vale/gitlab/AlertBoxNoteTip.yml | 15 | ||||
| -rw-r--r-- | doc/.vale/gitlab/AlertBoxStyle.yml | 8 | ||||
| -rw-r--r-- | doc/.vale/gitlab/CurlStringsQuoted.yml | 6 | ||||
| -rw-r--r-- | doc/.vale/gitlab/CurrentStatus.yml | 2 | ||||
| -rw-r--r-- | doc/.vale/gitlab/FutureTense.yml | 2 | ||||
| -rw-r--r-- | doc/.vale/gitlab/InternalLinkExtension.yml | 2 | ||||
| -rw-r--r-- | doc/.vale/gitlab/InternalLinkFormat.yml | 13 | ||||
| -rw-r--r-- | doc/.vale/gitlab/RelativeLinks.yml | 2 | ||||
| -rw-r--r-- | doc/.vale/gitlab/Simplicity.yml | 18 | ||||
| -rw-r--r-- | doc/.vale/gitlab/SubstitutionSuggestions.yml | 17 | ||||
| -rw-r--r-- | doc/.vale/gitlab/SubstitutionWarning.yml | 1 | ||||
| -rw-r--r-- | doc/.vale/gitlab/Substitutions.yml | 8 | ||||
| -rw-r--r-- | doc/.vale/gitlab/ToDo.yml | 14 | ||||
| -rw-r--r-- | doc/.vale/gitlab/VersionText.yml | 4 | ||||
| -rw-r--r-- | doc/.vale/gitlab/spelling-exceptions.txt | 2 | ||||
| -rw-r--r-- | doc/.vale/vale.tmpl | 51 |
20 files changed, 195 insertions, 16 deletions
diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml index 53690138300..494b1e42d2f 100644 --- a/doc/.vale/gitlab/Acronyms.yml +++ b/doc/.vale/gitlab/Acronyms.yml @@ -16,18 +16,24 @@ second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' exceptions: - ANSI - API + - ARM - ARN - ASCII - AWS + - BSD - CLI - CNAME - CORE - CPU - CSS - CSV + - DAG - DAST + - DHCP - DNS + - DVCS - EKS + - EOL - FAQ - FOSS - GCP @@ -41,6 +47,7 @@ exceptions: - HTTP - HTTPS - IAM + - IANA - IBM - IDE - IID @@ -48,13 +55,17 @@ exceptions: - IRC - ISO - JSON + - LAN - LDAP - LDAPS - LESS - LFS - LRU + - LTS - MIME + - MIT - MVC + - NAT - NFS - NGINX - NOTE @@ -67,7 +78,9 @@ exceptions: - PUT - RAM - REST + - RHEL - RPC + - RPM - RSA - RSS - RVM @@ -81,6 +94,7 @@ exceptions: - SLA - SMTP - SQL + - SSD - SSH - SSL - SSO @@ -88,6 +102,7 @@ exceptions: - SVN - TCP - TIP + - TLD - TLS - TODO - TOML @@ -95,6 +110,7 @@ exceptions: - URI - URL - USB + - UTC - UUID - VPC - WIP diff --git a/doc/.vale/gitlab/Admin.yml b/doc/.vale/gitlab/Admin.yml index 27a703c30c3..6d01882138a 100644 --- a/doc/.vale/gitlab/Admin.yml +++ b/doc/.vale/gitlab/Admin.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide.html level: warning ignorecase: true swap: - 'admin ?\w*': '(?:Admin Area|[Aa]dminist(ration|rator|er))' + 'admin ?\w*': '(?:Admin Area|[Aa]dminist(ration|rator|er|rative))' diff --git a/doc/.vale/gitlab/AlertBoxCaution.yml b/doc/.vale/gitlab/AlertBoxCaution.yml new file mode 100644 index 00000000000..49d4dc62ab5 --- /dev/null +++ b/doc/.vale/gitlab/AlertBoxCaution.yml @@ -0,0 +1,14 @@ +--- +# Error: gitlab.AlertBoxCaution +# +# Makes sure CAUTION: alert boxes follow standard formatting. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: "CAUTION: alert boxes must be of the format 'CAUTION: **Caution:**'. 'Caution' can be replaced with 'Warning' or 'Important'." +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes +level: warning +nonword: true +scope: raw +swap: + 'CAUTION: *?\*\*.*\*\*': 'CAUTION: \*\*(?:Caution|Warning|Important):\*\*' diff --git a/doc/.vale/gitlab/AlertBoxDanger.yml b/doc/.vale/gitlab/AlertBoxDanger.yml new file mode 100644 index 00000000000..2589d34614c --- /dev/null +++ b/doc/.vale/gitlab/AlertBoxDanger.yml @@ -0,0 +1,14 @@ +--- +# Error: gitlab.AlertBoxDanger +# +# Makes sure DANGER: alert boxes follow standard formatting. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: "DANGER: alert boxes must be of the format 'DANGER: **Warning:**'. 'Warning' can be replaced with 'Important', 'Deprecated', or 'Required'." +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes +level: error +nonword: true +scope: raw +swap: + 'DANGER: *?\*\*.*\*\*': 'DANGER: \*\*(?:Warning|Important|Deprecated|Required):\*\*' diff --git a/doc/.vale/gitlab/AlertBoxNoteTip.yml b/doc/.vale/gitlab/AlertBoxNoteTip.yml new file mode 100644 index 00000000000..0b480794476 --- /dev/null +++ b/doc/.vale/gitlab/AlertBoxNoteTip.yml @@ -0,0 +1,15 @@ +--- +# Error: gitlab.AlertBoxNoteTip +# +# Makes sure NOTE: and TIP: alert boxes follow standard formatting. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: "NOTE: and TIP: alert boxes must be of the format 'NOTE: **Note:**' or 'TIP: **Tip:**" +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes +level: warning +nonword: true +scope: raw +swap: + 'NOTE: *?\*\*.*\*\*': 'NOTE: \*\*Note:\*\*' + 'TIP: *?\*\*.*\*\*': 'TIP: \*\*Tip:\*\*' diff --git a/doc/.vale/gitlab/AlertBoxStyle.yml b/doc/.vale/gitlab/AlertBoxStyle.yml index 06743d95ea9..d15757d38fc 100644 --- a/doc/.vale/gitlab/AlertBoxStyle.yml +++ b/doc/.vale/gitlab/AlertBoxStyle.yml @@ -3,9 +3,7 @@ # # Makes sure alert boxes follow standard formatting. # -# Checks for 4 known issues: -# - Alert boxes with no colon, or colon outside the bold text -# - Known incorrect capitalization of the most commonly used alert box text +# Checks for 2 formatting issues: # - Alert boxes with the note text on the same line # - Alert boxes using blockquote formatting, like "> **Note:**" # @@ -16,7 +14,5 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert level: error scope: raw raw: - - '((NOTE|TIP|CAUTION|DANGER): \*\*[^:]*\*\*)|' - - '((NOTE: \*\*(NOTE|note):\*\*)|(TIP: \*\*(TIP|tip):\*\*)|(CAUTION: \*\*(CAUTION|caution):\*\*)|(DANGER: \*\*(DANGER|danger):\*\*))|' - - '((NOTE|TIP|CAUTION|DANGER): \*\*.*\*\*.+)|' + - '(\n(NOTE|TIP|CAUTION|DANGER): \*\*.*\*\*.+)|' - '((\n[> ]*(\*){1,2}(NOTE|Note|note|TIP|Tip|tip|CAUTION|Caution|caution|DANGER|Danger|danger):(\*){1,2}))' diff --git a/doc/.vale/gitlab/CurlStringsQuoted.yml b/doc/.vale/gitlab/CurlStringsQuoted.yml index 39ee9372947..a09c3fbfb51 100644 --- a/doc/.vale/gitlab/CurlStringsQuoted.yml +++ b/doc/.vale/gitlab/CurlStringsQuoted.yml @@ -1,12 +1,12 @@ --- # Warning: gitlab.CurlStringsQuoted # -# Ensures all codeblocks using curl quote any URL strings. +# Ensures all code blocks using curl quote any URL strings. # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: 'Curl commands must wrap URLs in double quotes ("): %s' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#curl-commands +message: 'For consistency across all cURL examples, always wrap the URL in double quotes ("): %s' +link: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#curl-commands level: warning scope: code raw: diff --git a/doc/.vale/gitlab/CurrentStatus.yml b/doc/.vale/gitlab/CurrentStatus.yml index 7368310eee8..584ac73aa17 100644 --- a/doc/.vale/gitlab/CurrentStatus.yml +++ b/doc/.vale/gitlab/CurrentStatus.yml @@ -5,7 +5,7 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: 'Avoid words like "%s" that promise future changes.' +message: 'Avoid words like "%s" that promise future changes, because documentation is about the current state of the product.' level: suggestion ignorecase: true link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid diff --git a/doc/.vale/gitlab/FutureTense.yml b/doc/.vale/gitlab/FutureTense.yml index 4a74ee87331..bba60dc9657 100644 --- a/doc/.vale/gitlab/FutureTense.yml +++ b/doc/.vale/gitlab/FutureTense.yml @@ -6,7 +6,7 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: 'Avoid using future tense: "%s"' +message: 'Avoid using future tense: "%s". Use present tense instead.' ignorecase: true level: warning link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid diff --git a/doc/.vale/gitlab/InternalLinkExtension.yml b/doc/.vale/gitlab/InternalLinkExtension.yml index 61a08e4a86c..9b5a3499815 100644 --- a/doc/.vale/gitlab/InternalLinkExtension.yml +++ b/doc/.vale/gitlab/InternalLinkExtension.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links level: error scope: raw raw: - - '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*\)' + - '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*?\)' diff --git a/doc/.vale/gitlab/InternalLinkFormat.yml b/doc/.vale/gitlab/InternalLinkFormat.yml new file mode 100644 index 00000000000..9a72778140e --- /dev/null +++ b/doc/.vale/gitlab/InternalLinkFormat.yml @@ -0,0 +1,13 @@ +--- +# Error: gitlab.InternalLinkFormat +# +# Checks that internal link paths don't start with "./", which is not needed. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Link "%s" must not start with "./".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation +level: error +scope: raw +raw: + - '\[.+\]\(\.\/.+?\)' diff --git a/doc/.vale/gitlab/RelativeLinks.yml b/doc/.vale/gitlab/RelativeLinks.yml index 7af20d8226f..1ae73472f8a 100644 --- a/doc/.vale/gitlab/RelativeLinks.yml +++ b/doc/.vale/gitlab/RelativeLinks.yml @@ -5,7 +5,7 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: 'Link "%s" must be relative.' +message: 'Link "%s" must be a relative link with a .md extension.' link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation level: error scope: raw diff --git a/doc/.vale/gitlab/Simplicity.yml b/doc/.vale/gitlab/Simplicity.yml new file mode 100644 index 00000000000..fa7a07c3e81 --- /dev/null +++ b/doc/.vale/gitlab/Simplicity.yml @@ -0,0 +1,18 @@ +--- +# Suggestion: gitlab.Simplicity +# +# Checks for words implying ease of use, to avoid cognitive dissonance for frustrated users. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.' +level: suggestion +ignorecase: true +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid +tokens: + - easy + - easily + - handy + - simple + - simply + - useful diff --git a/doc/.vale/gitlab/SubstitutionSuggestions.yml b/doc/.vale/gitlab/SubstitutionSuggestions.yml new file mode 100644 index 00000000000..df68961b1ce --- /dev/null +++ b/doc/.vale/gitlab/SubstitutionSuggestions.yml @@ -0,0 +1,17 @@ +--- +# Suggestion: gitlab.SubstitutionSuggestions +# +# Suggests better options for frequently misused terms at GitLab that are +# often - but not always - incorrect. +# +# For a list of all options, see https://errata-ai.github.io/vale/styles/ +extends: substitution +message: 'Consider "%s" instead of "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language +level: suggestion +ignorecase: true +swap: + since: because + once that: after that + once the: after the + once you: after you diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml index 68313a37e7d..ed0f8b498fe 100644 --- a/doc/.vale/gitlab/SubstitutionWarning.yml +++ b/doc/.vale/gitlab/SubstitutionWarning.yml @@ -18,3 +18,4 @@ swap: filesystem: file system info: information repo: repository + utilize: use diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml index 704c64f1fbd..3d1cf8057eb 100644 --- a/doc/.vale/gitlab/Substitutions.yml +++ b/doc/.vale/gitlab/Substitutions.yml @@ -25,5 +25,13 @@ swap: self hosted: self-managed self-hosted: self-managed styleguide: style guide + to login: to log in + can login: can log in + to log-in: to log in + can log-in: can log in + to signin: to sign in + can signin: can sign in + to sign-in: to sign in + can sign-in: can sign in x509: X.509 yaml: YAML diff --git a/doc/.vale/gitlab/ToDo.yml b/doc/.vale/gitlab/ToDo.yml new file mode 100644 index 00000000000..b3c5f6077b1 --- /dev/null +++ b/doc/.vale/gitlab/ToDo.yml @@ -0,0 +1,14 @@ +--- +# Warning: gitlab.ToDo +# +# You should not use "To Do", unless it refers to the UI element. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use "to-do item" in most cases, or "Add a to do" if referring to the UI button.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#feature-names +level: warning +ignorecase: false +swap: + '[Tt]o [Dd]o [Ii]tems?': to-do item + '\w* [Aa] [Tt]o [Dd]o': Add a to do diff --git a/doc/.vale/gitlab/VersionText.yml b/doc/.vale/gitlab/VersionText.yml index 3723170b169..e59b936ae3f 100644 --- a/doc/.vale/gitlab/VersionText.yml +++ b/doc/.vale/gitlab/VersionText.yml @@ -15,9 +15,9 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: '"%s" is not formatted correctly.' +message: 'This introduced-in line is not formatted correctly.' link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#text-for-documentation-requiring-version-text level: error scope: raw raw: - - '> (- ){0}\[?Introduced.+\n.+' + - '> (- ){0}\[?Introduced.+\n[^\n`]' diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index c0a85fc6b70..bbb5c892298 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -232,6 +232,7 @@ Laravel LDAP ldapsearch Leiningen +Lefthook Libravatar liveness Lograge @@ -347,6 +348,7 @@ proxied proxies proxyable proxying +pseudocode pseudonymized pseudonymizer Puma diff --git a/doc/.vale/vale.tmpl b/doc/.vale/vale.tmpl new file mode 100644 index 00000000000..36dfbd6b778 --- /dev/null +++ b/doc/.vale/vale.tmpl @@ -0,0 +1,51 @@ +{{- /* Modify Vale's output https://docs.errata.ai/vale/cli#--output */ -}} + +{{- /* Keep track of our various counts */ -}} + +{{- $e := 0 -}} +{{- $w := 0 -}} +{{- $s := 0 -}} +{{- $f := 0 -}} + +{{- /* Range over the linted files */ -}} + +{{- range .Files}} + +{{- $f = add1 $f -}} +{{- $path := .Path | underline -}} + +{{- /* Range over the file's alerts */ -}} + +{{- range .Alerts -}} + +{{- $error := "" -}} +{{- if eq .Severity "error" -}} + {{- $error = .Severity | red -}} + {{- $e = add1 $e -}} +{{- else if eq .Severity "warning" -}} + {{- $error = .Severity | yellow -}} + {{- $w = add1 $w -}} +{{- else -}} + {{- $error = .Severity | blue -}} + {{- $s = add1 $s -}} +{{- end}} + +{{- /* Variables setup */ -}} + +{{- $path = $path -}} +{{- $loc := printf "Line %d, position %d" .Line (index .Span 0) -}} +{{- $check := printf "%s" .Check -}} +{{- $message := printf "%s" .Message -}} +{{- $link := printf "%s" .Link -}} + +{{- /* Output */ -}} + +{{ $path }}: + {{ $loc }} (rule {{ $check }}) + {{ $error }}: {{ $message }} + More information: {{ $link }} + +{{end -}} +{{end -}} + +{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}}, and {{$s}} {{"suggestions" | blue}} found in {{$f}} {{$f | int | plural "file" "files"}}. |