From 2a5344868533856f94e015cfde1ab7497728baa0 Mon Sep 17 00:00:00 2001 From: Issy Long Date: Mon, 9 Dec 2019 18:42:14 +0000 Subject: [PATCH] Add Vale linting for our docs - I noticed that another open source project had taken the Homebrew style guide and made it into [Vale linting rules](https://github.com/testthedocs/vale-styles/tree/master/Homebrew). This copies them into here, so that we can make use of them. Thanks! - What use is a style guide if our own docs don't at least try to adhere to it? This aims to make the rules more visible to all contributors. - In order for these to do anything, you'll have to `brew install vale` and run `vale` in the root of this repo. It will look for Markdown files. - A next step would be adding this as a pre-commit hook, or... - The GitHub Action would have been really good, but [it doesn't support forks](https://github.com/errata-ai/vale-action#limitations). --- docs/_config.yml | 1 + docs/vale-styles/Homebrew/Abbreviations.yml | 12 ++++++++++++ docs/vale-styles/Homebrew/OxfordComma.yml | 8 ++++++++ docs/vale-styles/Homebrew/Pronouns.yml | 15 +++++++++++++++ docs/vale-styles/Homebrew/README.md | 1 + docs/vale-styles/Homebrew/Spacing.yml | 9 +++++++++ docs/vale-styles/Homebrew/Terms.yml | 9 +++++++++ docs/vale-styles/Homebrew/Titles.yml | 6 ++++++ docs/vale-styles/Homebrew/Trademarks.yml | 12 ++++++++++++ 9 files changed, 73 insertions(+) create mode 100644 docs/vale-styles/Homebrew/Abbreviations.yml create mode 100644 docs/vale-styles/Homebrew/OxfordComma.yml create mode 100644 docs/vale-styles/Homebrew/Pronouns.yml create mode 100644 docs/vale-styles/Homebrew/README.md create mode 100644 docs/vale-styles/Homebrew/Spacing.yml create mode 100644 docs/vale-styles/Homebrew/Terms.yml create mode 100644 docs/vale-styles/Homebrew/Titles.yml create mode 100644 docs/vale-styles/Homebrew/Trademarks.yml diff --git a/docs/_config.yml b/docs/_config.yml index 96bdaa69ef..8bffff2286 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -7,6 +7,7 @@ exclude: - bin - CNAME - Gemfile* + - vale-styles - vendor plugins: diff --git a/docs/vale-styles/Homebrew/Abbreviations.yml b/docs/vale-styles/Homebrew/Abbreviations.yml new file mode 100644 index 0000000000..95bd5b559e --- /dev/null +++ b/docs/vale-styles/Homebrew/Abbreviations.yml @@ -0,0 +1,12 @@ +--- +extends: substitution +message: Use '%s' +ignorecase: false +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#style-and-usage' +level: error +nonword: true +swap: + '\beg\b': e.g. + '\bie\b': i.e. + 'e\.g\.,': e.g. + 'i\.e\.,': i.e. diff --git a/docs/vale-styles/Homebrew/OxfordComma.yml b/docs/vale-styles/Homebrew/OxfordComma.yml new file mode 100644 index 0000000000..26f258763e --- /dev/null +++ b/docs/vale-styles/Homebrew/OxfordComma.yml @@ -0,0 +1,8 @@ +--- +extends: existence +message: 'No Oxford commas!' +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions' +scope: sentence +level: warning +tokens: + - '(?:[^,]+,){1,}\s\w+,\sand' diff --git a/docs/vale-styles/Homebrew/Pronouns.yml b/docs/vale-styles/Homebrew/Pronouns.yml new file mode 100644 index 0000000000..f1d5f30c33 --- /dev/null +++ b/docs/vale-styles/Homebrew/Pronouns.yml @@ -0,0 +1,15 @@ +--- +extends: existence +message: Avoid gender-specific language when not necessary. +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#personal-pronouns' +level: warning +ignorecase: true +tokens: + - him + - her + - she + - he + - his + - hers + - himself + - herself diff --git a/docs/vale-styles/Homebrew/README.md b/docs/vale-styles/Homebrew/README.md new file mode 100644 index 0000000000..a713f91d75 --- /dev/null +++ b/docs/vale-styles/Homebrew/README.md @@ -0,0 +1 @@ +Based on Homebrew's [Prose Style Guidelines](http://docs.brew.sh/Prose-Style-Guidelines.html). diff --git a/docs/vale-styles/Homebrew/Spacing.yml b/docs/vale-styles/Homebrew/Spacing.yml new file mode 100644 index 0000000000..2b3f2bdc10 --- /dev/null +++ b/docs/vale-styles/Homebrew/Spacing.yml @@ -0,0 +1,9 @@ +--- +extends: existence +message: "'%s' should have one space." +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions' +level: error +nonword: true +tokens: + - '[a-z][.?!][A-Z]' + - '[.?!] {2,}[A-Z]' diff --git a/docs/vale-styles/Homebrew/Terms.yml b/docs/vale-styles/Homebrew/Terms.yml new file mode 100644 index 0000000000..a020c67d63 --- /dev/null +++ b/docs/vale-styles/Homebrew/Terms.yml @@ -0,0 +1,9 @@ +--- +extends: substitution +message: Use '%s' instead of '%s'. +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#terminology-words-and-word-styling' +level: error +swap: + Pull Request: pull request + repo: repository + Rubocop: RuboCop diff --git a/docs/vale-styles/Homebrew/Titles.yml b/docs/vale-styles/Homebrew/Titles.yml new file mode 100644 index 0000000000..f54498fc22 --- /dev/null +++ b/docs/vale-styles/Homebrew/Titles.yml @@ -0,0 +1,6 @@ +--- +extends: capitalization +message: "'%s' should be in sentence case" +level: warning +scope: heading +match: $sentence diff --git a/docs/vale-styles/Homebrew/Trademarks.yml b/docs/vale-styles/Homebrew/Trademarks.yml new file mode 100644 index 0000000000..e1d335d46c --- /dev/null +++ b/docs/vale-styles/Homebrew/Trademarks.yml @@ -0,0 +1,12 @@ +--- +extends: existence +message: 'No "TM", ™, SM, ©, ®, or other explicit indicators of rights ownership or trademarks' +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions' +level: error +nonword: true +tokens: + - \bTM\b + - ™ + - \bSM\b + - © + - ®