From 04ec3367f08b53992b48f9cb1233ae7d9a7b2d57 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 11 Jul 2025 13:12:44 +0200 Subject: [PATCH 1/4] Add spell checker section to contributing guide --- docs/contributing/index.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 7d1de60b..938f96f4 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -63,6 +63,33 @@ You can get some hints of whom to contact by looking at [CODEOWNERS](https://git To minimise the overhead of the contributing to the documentation and speed up "time-to-published-docs" we do not have a formal review process. We will start simple, and add more formality as needed. +### Spell checker + +A spell checker workflow runs on all PRs to help catch simple typos. +If the spell checker finds words that it considers misspelled, it will add a comment like [this](https://github.com/eth-cscs/cscs-docs/pull/193#issuecomment-3056795496) to the PR, listing the words that it finds misspelled. + +The spell checker isn't always right and can be configured to ignore words. +Most frequently technical terms, project names, etc. will not be in the dictionaries. +There are three files used to configure words that get ignored: + +- `.github/actions/spelling/allow.txt` + - This is the main file for whitelisting words. + Each line of the file contains a word that is ignored by the spellchecker. + All lowercase words are matched with any capitalization, while words containing at least one uppercase letter are matched with the given capitalization. + Using the capitalized word is useful if you always want to ensure the same spelling, e.g. for names. +- `.github/actions/spelling/patterns.txt` + - This file is used to ignore words that match a given regular expression. + This file is useful to ignore e.g. URLs or markdown references. + Words that have unusual capitalization may also need to be added to this file to make sure they are ignored. + For example, "FirecREST" is normally recognized as two words: "Firec" and "REST", and adding "FirecREST" to `allow.txt` will not ignore the word. + In this case it can be ignored by adding it to `patterns.txt` +- `.github/actions/spelling/block-delimiters.txt` + - This file can be used to ignore words between begin- and end markers. + For example, code blocks starting and ending with `` ``` `` are ignored from spell checking as they often contain unusual words not in dictionaries. + +Additionally, the file `.github/actions/spelling/only.txt` contains a list of regular expressions used to match which files to check. +Only markdown files under the `docs` directory are checked. + [](){#ref-contributing-guidelines} ## Guidelines From e5d2243c86f079a336f300c259b807950365b846 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 11 Jul 2025 13:26:40 +0200 Subject: [PATCH 2/4] More spell checking in contributing guide --- docs/contributing/index.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 938f96f4..cc6580df 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -72,20 +72,24 @@ The spell checker isn't always right and can be configured to ignore words. Most frequently technical terms, project names, etc. will not be in the dictionaries. There are three files used to configure words that get ignored: -- `.github/actions/spelling/allow.txt` - - This is the main file for whitelisting words. - Each line of the file contains a word that is ignored by the spellchecker. - All lowercase words are matched with any capitalization, while words containing at least one uppercase letter are matched with the given capitalization. - Using the capitalized word is useful if you always want to ensure the same spelling, e.g. for names. -- `.github/actions/spelling/patterns.txt` - - This file is used to ignore words that match a given regular expression. - This file is useful to ignore e.g. URLs or markdown references. - Words that have unusual capitalization may also need to be added to this file to make sure they are ignored. - For example, "FirecREST" is normally recognized as two words: "Firec" and "REST", and adding "FirecREST" to `allow.txt` will not ignore the word. - In this case it can be ignored by adding it to `patterns.txt` -- `.github/actions/spelling/block-delimiters.txt` - - This file can be used to ignore words between begin- and end markers. - For example, code blocks starting and ending with `` ``` `` are ignored from spell checking as they often contain unusual words not in dictionaries. +- `.github/actions/spelling/allow.txt`: + This is the main file for whitelisting words. + Each line of the file contains a word that is ignored by the spellchecker. + All lowercase words are matched with any capitalization, while words containing at least one uppercase letter are matched with the given capitalization. + Using the capitalized word is useful if you always want to ensure the same spelling, e.g. for names. + +- `.github/actions/spelling/patterns.txt`: + This file is used to ignore words that match a given regular expression. + This file is useful to ignore e.g. URLs or markdown references. + Words that have unusual capitalization may also need to be added to this file to make sure they are ignored. + For example, "FirecREST" is normally recognized as two words: "Firec" and "REST", and adding "FirecREST" to `allow.txt` will not ignore the word. + In this case it can be ignored by adding it to `patterns.txt` + +- `.github/actions/spelling/block-delimiters.txt`: + This file can be used to ignore words between begin- and end markers. + For example, code blocks starting and ending with `` ``` `` are ignored from spell checking as they often contain unusual words not in dictionaries. + If adding words to `allow.txt` or `patterns.txt`, or ignoring blocks with `block-delimiters.list`, is not sufficient, you can as a last resort use the HTML comments `` and `!--end no spell check-->` to ignore spell checking for a larger block of text. + The comments will not be rendered in the final documentation. Additionally, the file `.github/actions/spelling/only.txt` contains a list of regular expressions used to match which files to check. Only markdown files under the `docs` directory are checked. From e62f97a9912f5bc1c20f9ac6bbc01241edd7fc50 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 11 Jul 2025 13:27:01 +0200 Subject: [PATCH 3/4] Fix spelling --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index cc6580df..192ac4b6 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -74,7 +74,7 @@ There are three files used to configure words that get ignored: - `.github/actions/spelling/allow.txt`: This is the main file for whitelisting words. - Each line of the file contains a word that is ignored by the spellchecker. + Each line of the file contains a word that is ignored by the spell checker. All lowercase words are matched with any capitalization, while words containing at least one uppercase letter are matched with the given capitalization. Using the capitalized word is useful if you always want to ensure the same spelling, e.g. for names. From 520234d70e5be5f4bdc39a437febad95020714c1 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 11 Jul 2025 13:31:10 +0200 Subject: [PATCH 4/4] Fix spell checking ignore comment --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 192ac4b6..469b91ec 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -88,7 +88,7 @@ There are three files used to configure words that get ignored: - `.github/actions/spelling/block-delimiters.txt`: This file can be used to ignore words between begin- and end markers. For example, code blocks starting and ending with `` ``` `` are ignored from spell checking as they often contain unusual words not in dictionaries. - If adding words to `allow.txt` or `patterns.txt`, or ignoring blocks with `block-delimiters.list`, is not sufficient, you can as a last resort use the HTML comments `` and `!--end no spell check-->` to ignore spell checking for a larger block of text. + If adding words to `allow.txt` or `patterns.txt`, or ignoring blocks with `block-delimiters.list`, is not sufficient, you can as a last resort use the HTML comments `` and `` to ignore spell checking for a larger block of text. The comments will not be rendered in the final documentation. Additionally, the file `.github/actions/spelling/only.txt` contains a list of regular expressions used to match which files to check.