diff --git a/.gitignore b/.gitignore index 5322edac20..6560ae2362 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ poc-docs/ docs/ .docusaurus testResults*.json +.hyperlint/reviewer/vale-style-guide/styles/Google/ \ No newline at end of file diff --git a/.hyperlint/config.yaml b/.hyperlint/config.yaml index b6664ca7e5..635ce72d06 100644 --- a/.hyperlint/config.yaml +++ b/.hyperlint/config.yaml @@ -1,4 +1,9 @@ content_dir: "/modules" -custom_style_guide: - enabled: true - path_to_style_guide_dir: "./.hyperlint/style-guide/" +reviewer: + custom_style_guide: + enabled: true + path_to_style_guide_dir: .hyperlint/reviewer/custom-style-guide + vale_style_guide: + check_status_upon_review_failure: failure + enabled: true + path_to_vale_ini_file: .hyperlint/reviewer/vale-style-guide/.vale.ini diff --git a/.hyperlint/reviewer/custom-style-guide/code-formatting.adoc b/.hyperlint/reviewer/custom-style-guide/code-formatting.adoc new file mode 100644 index 0000000000..34ce3db42b --- /dev/null +++ b/.hyperlint/reviewer/custom-style-guide/code-formatting.adoc @@ -0,0 +1,15 @@ += Redpanda Data Documentation Code Formatting Guidelines + +=== Commands and code + +Don’t start a sentence with a command or code. Instead, try to move the code into the middle of the sentence. Introduce the command with the more descriptive word “run” instead of “use the X command". ++ +*Correct:* Run the `rpk topic create` command to create a new topic. ++ +*Incorrect:* `rpk topic create` creates a new topic. + +Similarly, do not start a sentence with a filename. ++ +*Correct:* The `redpanda.yaml` file contains configuration parameters. ++ +*Incorrect:* `redpanda.yaml` contains configuration parameters. diff --git a/.hyperlint/reviewer/custom-style-guide/grammar.adoc b/.hyperlint/reviewer/custom-style-guide/grammar.adoc new file mode 100644 index 0000000000..550c282453 --- /dev/null +++ b/.hyperlint/reviewer/custom-style-guide/grammar.adoc @@ -0,0 +1,6 @@ += Redpanda Data Grammar Guidelines + +Here are some high level guidelines for additions to the documentation: +- Check for spelling and grammar issues. +- Consider readability and clarity when writing. +- Avoid long or wordy sentences. \ No newline at end of file diff --git a/.hyperlint/reviewer/custom-style-guide/styles.adoc b/.hyperlint/reviewer/custom-style-guide/styles.adoc new file mode 100644 index 0000000000..6a4b36c18b --- /dev/null +++ b/.hyperlint/reviewer/custom-style-guide/styles.adoc @@ -0,0 +1,35 @@ += Redpanda Data Documentation Style Guidelines + +=== Notes and warnings + +Redpanda product documentation uses AsciiDoc note and warning admonitions: + +[cols="1,1",options="header"] +|=== +| Notice | Description + +| NOTE +| A supplement to the documentation with helpful information. + +| TIP +| Describes a way to make things easier or indicates a best practice. + +| CAUTION +| A warning that certain behavior is unexpected or may have unintended consequences. + +| IMPORTANT +| An important note. +|=== + +== Numbers + +For whole numbers between one and nine, spell out the number (for example, nine instead of 9). For numbers greater than 9, or any decimal or negative number, use Arabic numerals (for example, 1.5 or -2). + +* *Correct:* To run Redpanda in a three-node cluster, use this command: `rpk container start -n 3` +* *Incorrect:* To run Redpanda in a 3-node cluster, use this command: `rpk container start -n 3` + +The exception to this is within code or when you’re referring to a default value. For example: + +* *Correct:* cloud_storage_upload_ctrl_d_coeff - The derivative coefficient for the upload controller. Default is 0. +* *Incorrect:* cloud_storage_upload_ctrl_d_coeff - The derivative coefficient for the upload controller. Default is zero. + diff --git a/.hyperlint/reviewer/vale-style-guide/.vale.ini b/.hyperlint/reviewer/vale-style-guide/.vale.ini new file mode 100644 index 0000000000..3a1a62b7fd --- /dev/null +++ b/.hyperlint/reviewer/vale-style-guide/.vale.ini @@ -0,0 +1,26 @@ +StylesPath = styles + +Packages = Google +# Use packages to add default rules published by the community +Vocab = CustomVocab +# This is in the config/vocabularies folder +MinAlertLevel = warning # error, warning, suggestion +# When conflicting rules exist, those defined in CustomStyle (listed last) +# override those from Google and Vale. This ensures that our custom rules have the final say. +[*] +BasedOnStyles = Vale, Google, CustomStyle +# Add a package here if you want to use it +# CustomStyle is defined in the styles folder + +# Vale.Spelling = NO # comment this in to disable spelling checks +# Vale.Terms = NO # comment this in to disable terms checks + + +[asciidoctor] +experimental = YES +attribute-missing = drop + +[*.adoc] +# Put ASCIIDOC specific rules here +# Disable this rule because Google wants level 1 headings to be in sentence case. +disable = Google.Headings-warning diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/MeaningfulLinkText.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/MeaningfulLinkText.yml new file mode 100644 index 0000000000..ba649415b9 --- /dev/null +++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/MeaningfulLinkText.yml @@ -0,0 +1,17 @@ +extends: existence +message: "Rewrite the link text for `%s` to be more descriptive." +level: warning +ignorecase: true +scope: raw +nonword: true +tokens: + - "link:.*\\[here\\]" + - "link:.*\\[this page\\]" + - "link:.*\\[read more\\]" + - "link:.*\\[see this blog post\\]" + - "link:.*\\[blog post\\]" + - "<<.*,here>>" + - "<<.*,this page>>" + - "<<.*,read more>>" + - "<<.*,see this blog post>>" + - "<<.*,blog post>>" diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/OptionalPlurals.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/OptionalPlurals.yml new file mode 100644 index 0000000000..4a8767d6f5 --- /dev/null +++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/OptionalPlurals.yml @@ -0,0 +1,12 @@ +extends: existence +message: "Don't use plurals in parentheses such as in '%s'." +link: "https://developers.google.com/style/plurals-parentheses" +level: error +nonword: true +action: + name: edit + params: + - trim_right + - "(s)" +tokens: + - '\b\w+\(s\)' diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SentenceLength.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SentenceLength.yml new file mode 100644 index 0000000000..19772ea897 --- /dev/null +++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SentenceLength.yml @@ -0,0 +1,8 @@ +description: Try to keep sentences short (< 30 words). Split up sentence if possible. +link: https://hyperlint.com/vale/rule/sentence-length-rule/ +extends: occurrence +message: "Try to keep sentences short (< 30 words)." +scope: sentence +level: suggestion +max: 30 +token: \b(\w+)\b diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml new file mode 100644 index 0000000000..b4caf30347 --- /dev/null +++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml @@ -0,0 +1,25 @@ +# See this rule for more information: https://vale.sh/docs/checks/substitution/ +extends: substitution +ignorecase: true +level: warning +message: Consider using '%s' instead of '%s' +action: + name: replace +swap: + as well as: and + back end: backend + config: configuration + data center: datacenter + e.g.: for example + etc.: and so on + for instance: for example + foo: "[use meaningful name]" + i.e.: that is + master: primary|main|original|parent|publisher|leader|active + once: after + should: will|must + slave: secondary|worker + multi datacenter: multi-datacenter + multi-cloud: multicloud + on-premise: on-premises + on-prem: on-premises diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/We.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/We.yml new file mode 100644 index 0000000000..c7ac7d3622 --- /dev/null +++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/We.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Try to avoid using first-person plural like '%s'." +link: 'https://developers.google.com/style/pronouns#personal-pronouns' +level: warning +ignorecase: true +tokens: + - we + - we'(?:ve|re) + - ours? + - us + - let's diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/WeakModifiers.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/WeakModifiers.yml new file mode 100644 index 0000000000..c7241b1325 --- /dev/null +++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/WeakModifiers.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Avoid the use of the word `%s`, it's a weak modifier." +level: warning +ignorecase: true +scope: raw +nonword: true +tokens: + - very + - extremely + - really + - quite diff --git a/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/accept.txt b/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/accept.txt new file mode 100644 index 0000000000..bd4f6a4468 --- /dev/null +++ b/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/accept.txt @@ -0,0 +1,6 @@ +ID +Hyperlint +Redpanda Data +Redpanda +YAML +Zookeeper \ No newline at end of file diff --git a/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/reject.txt b/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/reject.txt new file mode 100644 index 0000000000..976ae370b7 --- /dev/null +++ b/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/reject.txt @@ -0,0 +1,3 @@ +and/or +please +via \ No newline at end of file diff --git a/.hyperlint/style-guide/grammar.md b/.hyperlint/style-guide/grammar.md deleted file mode 100644 index 04c897936e..0000000000 --- a/.hyperlint/style-guide/grammar.md +++ /dev/null @@ -1,2 +0,0 @@ -Check for spelling and grammar issues. -Also consider readability and clarity of content. \ No newline at end of file