From 15bba0ee3bc1aa12fc88af31e917b5354a2a80c1 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 23 Aug 2023 17:10:27 +0100 Subject: [PATCH] Add some Vale styles (#2963) * add some styles Signed-off-by: Jo Stichbury * Tweaks to styles Signed-off-by: Jo Stichbury * more tweaks Signed-off-by: Jo Stichbury * Revise some styles Signed-off-by: Jo Stichbury * Revise severity of some styles Signed-off-by: Jo Stichbury * Update .github/styles/Kedro/words.yml Co-authored-by: Deepyaman Datta --------- Signed-off-by: Jo Stichbury Co-authored-by: Deepyaman Datta --- .github/styles/Kedro/abbreviations.yml | 11 ++ .github/styles/Kedro/gender.yml | 13 ++ .github/styles/Kedro/headings.yml | 56 ++++++ .github/styles/Kedro/inclusive.yml | 12 ++ .github/styles/Kedro/links.yml | 24 +++ .github/styles/Kedro/oxfordcomma.yml | 6 + .github/styles/Kedro/pronouns.yml | 11 ++ .github/styles/Kedro/quotes.yml | 10 ++ .github/styles/Kedro/sentencelength.yml | 11 ++ .github/styles/Kedro/toowordy.yml | 218 ++++++++++++++++++++++++ .github/styles/Kedro/ukspelling.yml | 25 +++ .github/styles/Kedro/weaselwords.yml | 207 ++++++++++++++++++++++ .github/styles/Kedro/words.yml | 53 ++++++ docs/source/data/data_catalog.md | 1 + 14 files changed, 658 insertions(+) create mode 100644 .github/styles/Kedro/abbreviations.yml create mode 100644 .github/styles/Kedro/gender.yml create mode 100644 .github/styles/Kedro/headings.yml create mode 100644 .github/styles/Kedro/inclusive.yml create mode 100644 .github/styles/Kedro/links.yml create mode 100644 .github/styles/Kedro/oxfordcomma.yml create mode 100644 .github/styles/Kedro/pronouns.yml create mode 100644 .github/styles/Kedro/quotes.yml create mode 100644 .github/styles/Kedro/sentencelength.yml create mode 100644 .github/styles/Kedro/toowordy.yml create mode 100644 .github/styles/Kedro/ukspelling.yml create mode 100644 .github/styles/Kedro/weaselwords.yml create mode 100644 .github/styles/Kedro/words.yml diff --git a/.github/styles/Kedro/abbreviations.yml b/.github/styles/Kedro/abbreviations.yml new file mode 100644 index 0000000000..345ecc31a4 --- /dev/null +++ b/.github/styles/Kedro/abbreviations.yml @@ -0,0 +1,11 @@ +extends: substitution +message: "Use '%s' instead of abbreviations like '%s'." +ignorecase: true +level: warning +nonword: true +action: + name: replace +swap: + '\b(?:eg|e\.g\.|eg\.)[\s,]': for example + '\b(?:ie|i\.e\.|ie\.)[\s,]': that is + '\b(?:etc)[\s\n,.]': and more diff --git a/.github/styles/Kedro/gender.yml b/.github/styles/Kedro/gender.yml new file mode 100644 index 0000000000..f06d0f9cc5 --- /dev/null +++ b/.github/styles/Kedro/gender.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Use a gender-neutral pronoun instead of '%s'." +level: error +ignorecase: true +tokens: + - he/she + - s/he + - \(s\)he + - \bhe\b + - \bhim\b + - \bhis\b + - \bshe\b + - \bher\b diff --git a/.github/styles/Kedro/headings.yml b/.github/styles/Kedro/headings.yml new file mode 100644 index 0000000000..3c83043bd3 --- /dev/null +++ b/.github/styles/Kedro/headings.yml @@ -0,0 +1,56 @@ +extends: capitalization +message: "'%s' should use sentence-style capitalization." +level: warning +scope: heading +match: $sentence +exceptions: + - Kedro + - Kedro-Viz + - Airflow + - Amazon + - Amazon Web Services + - AWS Step Functions + - AWS Systems Manager + - Azure + - Azure App Service + - Azure App Service Plan + - Azure Blob Storage + - Azure Event Hub + - CI/CD + - DataCatalog + - Data Catalog + - Docker + - Docker Compose + - Docker Swarm + - Dockerfile + - GitHub + - GitHub Actions + - Google + - Google Analytics + - Google Cloud + - Google Cloud Functions + - GraphQL + - Hook + - Hooks + - IDs + - Jenkins + - JFrog + - JFrog Artifactory + - Jira + - Kafka + - Kubernetes + - Kubernetes Engine + - Kubernetes Pod + - Kubernetes Service + - Lambda + - Linux + - MySQL + - Python + - QuantumBlack + - QuantumBlack Labs + - Red Hat + - Redis + - Slack + - Ubuntu + - Unix + - URLs diff --git a/.github/styles/Kedro/inclusive.yml b/.github/styles/Kedro/inclusive.yml new file mode 100644 index 0000000000..21792cc49f --- /dev/null +++ b/.github/styles/Kedro/inclusive.yml @@ -0,0 +1,12 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +ignorecase: true +level: error +action: + name: replace +swap: + # bad: good + 'black ?list': 'disallow list|exclude list' + 'master': primary + 'slave': secondary + 'white ?list': 'allow list|include list' diff --git a/.github/styles/Kedro/links.yml b/.github/styles/Kedro/links.yml new file mode 100644 index 0000000000..aa7597d554 --- /dev/null +++ b/.github/styles/Kedro/links.yml @@ -0,0 +1,24 @@ +extends: substitution +message: "Avoid vague text in links like '%s' unless you can pair it with more descriptive text." +link: 'https://github.com/kedro-org/kedro/wiki/Kedro-documentation-style-guide' +ignorecase: true +scope: raw +nonword: true +level: error + +swap: +# For the word 'here' in Markdown and HTML links + '\[here\]\(.*?\)': 'here' + '\s*here\s*': 'here' + +# For the word 'this' in Markdown and HTML links + '\[this\]\(.*?\)': 'this' + '\s*this\s*': 'this' + +# For the word 'page' in Markdown and HTML links + '\[page\]\(.*?\)': 'page' + '\s*page\s*': 'page' + +# For the phrase 'this page' in Markdown and HTML links + '\[this page\]\(.*?\)': 'this page' + '\s*this page\s*': 'this page' diff --git a/.github/styles/Kedro/oxfordcomma.yml b/.github/styles/Kedro/oxfordcomma.yml new file mode 100644 index 0000000000..464d6e6997 --- /dev/null +++ b/.github/styles/Kedro/oxfordcomma.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Use the Oxford comma in '%s'." +scope: sentence +level: suggestion +tokens: + - '(?:[^,]+,){1,}\s\w+\s(?:and|or)' diff --git a/.github/styles/Kedro/pronouns.yml b/.github/styles/Kedro/pronouns.yml new file mode 100644 index 0000000000..cea1aca18e --- /dev/null +++ b/.github/styles/Kedro/pronouns.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Avoid first-person singular pronouns such as '%s'." +level: warning +nonword: true +tokens: + - (?<=^|\s)I(?=\s) + - (?<=^|\s)I,(?=\s) + - \bI'm\b + - (?<=\s)[Mm]e\b + - (?<=\s)[Mm]y\b + - (?<=\s)[Mm]ine\b diff --git a/.github/styles/Kedro/quotes.yml b/.github/styles/Kedro/quotes.yml new file mode 100644 index 0000000000..7e4ed44be0 --- /dev/null +++ b/.github/styles/Kedro/quotes.yml @@ -0,0 +1,10 @@ +extends: existence +message: Use straight quotes instead of smart quotes. +level: warning +nonword: true +action: +tokens: + - “ + - ” + - ‘ + - ’ diff --git a/.github/styles/Kedro/sentencelength.yml b/.github/styles/Kedro/sentencelength.yml new file mode 100644 index 0000000000..6c135a84c5 --- /dev/null +++ b/.github/styles/Kedro/sentencelength.yml @@ -0,0 +1,11 @@ +extends: occurrence +message: "Try to keep your sentence length to 30 words or fewer." +level: suggestion +# Here, we're counting the number of words +# in a sentence. +# +# If there are more than 30, we'll flag it. +scope: sentence +ignorecase: false +max: 30 +token: (\w+) diff --git a/.github/styles/Kedro/toowordy.yml b/.github/styles/Kedro/toowordy.yml new file mode 100644 index 0000000000..262b5ca419 --- /dev/null +++ b/.github/styles/Kedro/toowordy.yml @@ -0,0 +1,218 @@ +# Write Good's "Too wordy" rule https://github.com/testthedocs/vale-styles/blob/master/write-good/TooWordy.yml +extends: existence +message: "'%s' is too wordy" +ignorecase: true +level: warning +tokens: + - a number of + - abundance + - accede to + - accelerate + - accentuate + - accompany + - accomplish + - accorded + - accrue + - acquiesce + - acquire + - adjacent to + - adjustment + - admissible + - advantageous + - adversely impact + - advise + - aforementioned + - aggregate + - aircraft + - all of + - all things considered + - alleviate + - allocate + - along the lines of + - already existing + - alternatively + - amazing + - ameliorate + - anticipate + - apparent + - appreciable + - as a matter of fact + - as a means of + - as far as I'm concerned + - as of yet + - as to + - as yet + - ascertain + - assistance + - at the present time + - at this time + - attain + - attributable to + - because of the fact that + - belated + - benefit from + - bestow + - by means of + - by virtue of the fact that + - by virtue of + - cease + - close proximity + - commence + - comply with + - concerning + - consequently + - consolidate + - constitutes + - demonstrate + - depart + - designate + - discontinue + - due to the fact that + - each and every + - economical + - eliminate + - elucidate + - employ + - endeavor + - enumerate + - equitable + - equivalent + - evaluate + - evidenced + - exclusively + - expedite + - expend + - expiration + - facilitate + - factual evidence + - feasible + - finalise + - first and foremost + - for all intents and purposes + - for the most part + - for the purpose of + - forfeit + - formulate + - have a tendency to + - honest truth + - however + - if and when + - impacted + - implement + - in a manner of speaking + - in a timely manner + - in a very real sense + - in accordance with + - in addition + - in all likelihood + - in an effort to + - in between + - in excess of + - in lieu of + - in light of the fact that + - in many cases + - in my opinion + - in order to + - in regard to + - in some instances + - in terms of + - in the case of + - in the event that + - in the final analysis + - in the nature of + - in the near future + - in the process of + - inception + - incumbent upon + - indicate + - indication + - initiate + - irregardless + - is applicable to + - is authorised to + - is responsible for + - it is essential + - it seems that + - it was + - magnitude + - maximum + - methodology + - minimise + - modify + - monitor + - multiple + - necessitate + - nevertheless + - not certain + - not many + - not often + - not unless + - not unlike + - notwithstanding + - null and void + - numerous + - objective + - obligate + - obtain + - on the contrary + - on the other hand + - one particular + - optimum + - overall + - owing to the fact that + - participate + - particulars + - pass away + - pertaining to + - point in time + - portion + - possess + - preclude + - previously + - prior to + - prioritise + - procure + - proficiency + - provided that + - purchase + - put simply + - readily apparent + - refer back + - regarding + - relocate + - remainder + - remuneration + - requirement + - reside + - residence + - retain + - satisfy + - shall + - should you wish + - similar to + - solicit + - span across + - strategise + - subsequent + - substantial + - successfully complete + - sufficient + - terminate + - the month of + - the point I am trying to make + - therefore + - time period + - took advantage of + - transmit + - transpire + - type of + - until such time as + - utilisation + - utilise + - validate + - various different + - what I mean to say is + - whether or not + - with respect to + - with the exception of + - witnessed diff --git a/.github/styles/Kedro/ukspelling.yml b/.github/styles/Kedro/ukspelling.yml new file mode 100644 index 0000000000..fbd59b50ec --- /dev/null +++ b/.github/styles/Kedro/ukspelling.yml @@ -0,0 +1,25 @@ +extends: existence +message: "In general, use UK English spelling instead of '%s'." +link: 'https://github.com/kedro-org/kedro/wiki/Kedro-documentation-style-guide' +ignorecase: true +level: warning +tokens: + - '(?:\w+)nized' + - '(?:\w+)ize' + - '(?:\w+)log' + - '(?:\w+)lor' + - '(?:\w+)lyze' +exceptions: + - backlog + - blog + - capsize + - catalog + - Catalog + - DataCatalog + - dialog + - log + - maize + - prize + - seize + - size + - tailor diff --git a/.github/styles/Kedro/weaselwords.yml b/.github/styles/Kedro/weaselwords.yml new file mode 100644 index 0000000000..d6c6f73e09 --- /dev/null +++ b/.github/styles/Kedro/weaselwords.yml @@ -0,0 +1,207 @@ +# Write Good's Weasel Words rule https://github.com/testthedocs/vale-styles/blob/master/write-good/Weasel.yml +extends: existence +message: "'%s' is a weasel word!" +ignorecase: true +level: warning +tokens: + - absolutely + - accidentally + - additionally + - allegedly + - alternatively + - angrily + - anxiously + - approximately + - awkwardly + - badly + - barely + - beautifully + - blindly + - boldly + - bravely + - brightly + - briskly + - bristly + - bubbly + - busily + - calmly + - carefully + - carelessly + - cautiously + - cheerfully + - clearly + - closely + - coldly + - completely + - consequently + - correctly + - courageously + - crinkly + - cruelly + - crumbly + - cuddly + - currently + - daily + - daringly + - deadly + - definitely + - deliberately + - doubtfully + - dumbly + - eagerly + - easily + - elegantly + - enormously + - enthusiastically + - equally + - especially + - eventually + - exactly + - exceedingly + - exclusively + - extremely + - fairly + - faithfully + - fatally + - fiercely + - finally + - fondly + - few + - foolishly + - fortunately + - frankly + - frantically + - generously + - gently + - giggly + - gladly + - gracefully + - greedily + - happily + - hardly + - hastily + - healthily + - heartily + - helpfully + - honestly + - hourly + - hungrily + - hurriedly + - immediately + - impatiently + - inadequately + - ingeniously + - innocently + - inquisitively + - interestingly + - irritably + - jiggly + - joyously + - justly + - kindly + - largely + - lately + - lazily + - likely + - literally + - lonely + - loosely + - loudly + - loudly + - luckily + - madly + - many + - mentally + - mildly + - monthly + - mortally + - mostly + - mysteriously + - neatly + - nervously + - nightly + - noisily + - normally + - obediently + - occasionally + - only + - openly + - painfully + - particularly + - patiently + - perfectly + - politely + - poorly + - powerfully + - presumably + - previously + - promptly + - punctually + - quarterly + - quickly + - quietly + - rapidly + - rarely + - really + - recently + - recklessly + - regularly + - remarkably + - relatively + - reluctantly + - repeatedly + - rightfully + - roughly + - rudely + - sadly + - safely + - selfishly + - sensibly + - seriously + - sharply + - shortly + - shyly + - significantly + - silently + - simply + - sleepily + - slowly + - smartly + - smelly + - smoothly + - softly + - solemnly + - sparkly + - speedily + - stealthily + - sternly + - stupidly + - substantially + - successfully + - suddenly + - surprisingly + - suspiciously + - swiftly + - tenderly + - tensely + - thoughtfully + - tightly + - timely + - truthfully + - unexpectedly + - unfortunately + - usually + - very + - victoriously + - violently + - vivaciously + - warmly + - waverly + - weakly + - wearily + - weekly + - wildly + - wisely + - worldly + - wrinkly + - yearly diff --git a/.github/styles/Kedro/words.yml b/.github/styles/Kedro/words.yml new file mode 100644 index 0000000000..5ed27dd319 --- /dev/null +++ b/.github/styles/Kedro/words.yml @@ -0,0 +1,53 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +ignorecase: false +level: warning +action: + name: replace +swap: + # bad: good + 'acknowledgement': 'acknowledgment' + 'auto-complete': 'autocomplete' + 'a number of': 'few|several|many' + 'and/or': 'and|or|either or' + 'back end': 'backend' + 'bear in mind': 'keep in mind' + 'culprit': 'cause' + 'data set': 'dataset' + 'drill down|drilling down|drill into|drilling into': 'examine|investigate|analyze' + 'figure out': 'determine' + 'fine tune|fine-tune': 'customize|optimize|refine' + 'for the most part': 'generally|usually' + 'front end': 'frontend' + 'highly|very': '' + 'hit': 'click|select' + 'in order to': 'to' + 'keep in mind': 'consider' + 'left up to': 'determined by' + 'leverage': 'use' + 'multi-alert': 'multi alert' + 'Note that': '**Note**:' + 'obviously|obvious': '' + 'on the fly': 'real-time|real time' + 'once': 'after' + 'play a hand': 'influence' + 'please|just': '' + 'easily|easy': '' + 'quickly|quick': '' + 'screen board': 'screenboard' + 'simply|simple': '' + 'stand for': 'represents|means' + 'reenable': 're-enable' + 'run time': 'runtime' + 'refer to|visit': 'see|read|follow' + 'time board': 'timeboard' + 'time series': 'timeseries' + 'toplist': 'top list' + 'tradeoff': 'trade-off' + 'turnkey': 'ready to use' + 'under the hood': '' + 'utilize': 'use' + 'via': 'with|through' + 'visit': 'see|read' + 'webserver': 'web server' + 'web site': 'website' diff --git a/docs/source/data/data_catalog.md b/docs/source/data/data_catalog.md index 241e339635..b4a6c4d7da 100644 --- a/docs/source/data/data_catalog.md +++ b/docs/source/data/data_catalog.md @@ -1,5 +1,6 @@ # Introduction to the Data Catalog + In a Kedro project, the Data Catalog is a registry of all data sources available for use by the project. It is specified with a YAML catalog file that maps the names of node inputs and outputs as keys in the `DataCatalog` class. This page introduces the basic sections of `catalog.yml`, which is the file used to register data sources for a Kedro project.