Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add spell-checker to contributing docs #2504

Merged
merged 26 commits into from
Jan 12, 2024
Merged
Show file tree
Hide file tree
Changes from 21 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
33e5df5
docs: add spell-checker to contribute/docs
StackScribe Nov 15, 2023
b8dbede
internals
StackScribe Nov 27, 2023
18ec002
markdownlint-fix
StackScribe Nov 27, 2023
48bde63
Update docs/content/en/contribute/docs/spell-check/_index.md
StackScribe Nov 29, 2023
210573d
Update docs/content/en/contribute/docs/spell-check/_index.md
StackScribe Nov 29, 2023
3a013f1
Update docs/content/en/contribute/docs/spell-check/_index.md
StackScribe Nov 29, 2023
9dbe51d
Update docs/content/en/contribute/docs/spell-check/_index.md
StackScribe Nov 29, 2023
ef702d3
Update docs/content/en/contribute/docs/spell-check/_index.md
StackScribe Nov 29, 2023
f74d7cf
Update docs/content/en/contribute/docs/spell-check/_index.md
StackScribe Nov 29, 2023
936ae3a
Update docs/content/en/contribute/docs/spell-check/_index.md
StackScribe Nov 29, 2023
984331f
correct config info per mo`
StackScribe Dec 13, 2023
139ab24
Merge branch 'main' into 1114-spell-docs
StackScribe Dec 14, 2023
47a3e8f
move file to docs-new
StackScribe Dec 19, 2023
6abbb7b
Merge branch 'main' into 1114-spell-docs
mowies Dec 19, 2023
fc14889
Update docs-new/docs/contribute/docs/spell-check.md
StackScribe Dec 19, 2023
66f8e9a
Update docs-new/docs/contribute/docs/spell-check.md
StackScribe Dec 19, 2023
6546551
Update docs-new/docs/contribute/docs/spell-check.md
StackScribe Dec 19, 2023
893b3fe
Update docs-new/docs/contribute/docs/spell-check.md
StackScribe Dec 19, 2023
7d9521f
spelling error for testing
StackScribe Dec 19, 2023
3394164
another spelling error for testing
StackScribe Dec 19, 2023
4a5eeab
point to job summary for errors
StackScribe Dec 19, 2023
7dcebbc
Update docs-new/docs/contribute/docs/spell-check.md
StackScribe Dec 21, 2023
1066918
Update docs-new/docs/contribute/docs/spell-check.md
StackScribe Dec 21, 2023
5d51c06
remove ref to community/slack
StackScribe Dec 21, 2023
a952fdd
Merge branch 'main' into 1114-spell-docs
StackScribe Jan 5, 2024
66bdf70
Apply suggestions from code review
odubajDT Jan 5, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions docs-new/docs/contribute/docs/spell-check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Spell Checker

All PRs that are pushed to a Keptn repository
are run through a spell checker that is based on the
[check-spelling](https://github.com/check-spelling/check-spelling)
GitHub action.

Note, however, that you are still responsible for reading your text carefully.
The tool does not flag if you used a real word that is not the right word,
if you misuse "setup" versus "set up", and so forth.

## Handling Spell Checker errors

If you get a Spell Checker error:

1. Right-click the `details` link for Spell Checker
StackScribe marked this conversation as resolved.
Show resolved Hide resolved
StackScribe marked this conversation as resolved.
Show resolved Hide resolved
in the CI results section of your PR.
1. Search for "job summary" and click the link to that report.
StackScribe marked this conversation as resolved.
Show resolved Hide resolved
1. This shows the word(s) that caused Spell Checker to fail.

- If these are genuine misspellings,
correct the spelling in your local branch
or using the GitHub editor
and push the new commit to resolve the errors.

- If a word that is flagged is a legitimate word,
follow the instructions in the report
to propose adding it to our [dictionary](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/actions/spelling/expect.txt).
This request will be added to your PR for review
and, if approved, will be merged when the PR is merged.

- If your PR includes a file that should not be spell-checked,
you can add it to the
[excludes.txt](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/actions/spelling/excludes.txt) file
as part of your PR.
It will be reviewed and, if approved,
merged as part of your PR.

For more details about handling errors that are found, see the
[Check-spelling docs](https://docs.check-spelling.dev/).

## Implementation details

For full technical details about the spell checker, see:

- [check-spelling documentation](https://docs.check-spelling.dev/)
- [check-spelling GitHub repository](https://github.com/check-spelling/check-spelling)

The Keptn spell checker checks both documentation and code for spelling,
based on a set of dictionaries:

- We use general English language and technical terminology
from dictionaries that are provided and maintained by check-spelling.
The configuration is specified in files in the
[.github/actions/spelling](https://github.com/keptn/lifecycle-toolkit/tree/main/.github/actions/spelling)
directory.
[expect.txt](https://github.com/keptn/lifecycle-toolkit/tree/main/.github/actions/spelling)
odubajDT marked this conversation as resolved.
Show resolved Hide resolved
lists Keptn terms for both documentation and code.
- We also use the specialized technical dictionaries provided by check-spelling specific domains
or programming languages such as Kubernetes, Go or HTML.
The dictionaries we use are specified in the
[.github/workflows/spell-checker.yml](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/workflows/spell-checker.yml)
file.

Check-spelling supports both American and British spelling
and both are allowed in the Keptn documentation.

Check-spelling provides dictionaries for a number of non-English languages
but we do not currently use those.

Note that Check-spelling does not check for proper capitalization of terms.
All dictionary terms are listed with lowercase letters.
Check-spelling recognizes capitalized versions of these words but,
if capitalized words are listed in a dictionary,
check-spelling rejects non-capitalized forms
which are common in code.
80 changes: 80 additions & 0 deletions docs/content/en/contribute/docs/spell-check/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
title: Spell checker
description: How to work with the spell checker
weight: 375
---

All PRs that are pushed to a Keptn repository
are run through a spell checker that is based on the
[check-spelling](https://github.com/check-spelling/check-spelling)
GitHub action.

Note, however, that you are still responsible for reading your text carefully.
The tool does not flag if you used a real word that is not the right word,
if you misuse "setup" versus "set up", and so forth.

## Handling Spell Checker errors

If you get a Spell Checker error:

1. Right-click the `details` link for Spell Checker.
1. If you do not want to read through the whole (and rather verbose) log,
type `unrecognized words` in the search box at the top.
1. This shows the word(s) that caused Spell Checker to fail.

- If these are genuine misspellings,
correct the spelling in your local branch
or using the github editor
and push the new commit to resolve the errors.

- If a word that is flagged is a legitimate word,
follow the instructions in the report
to propose adding it to our dictionary.
This request will be added to your PR for review
and, if approved, will be merged when the PR is merged.

- If your PR includes a file that should not be spell-checked,
you can add it to the
[excludes.txt](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/actions/spelling/excludes.txt) file
as part of your PR.
It will be reviewed and, if approved,
merged as part of your PR.

For more details about handling errors that are found, see the
[Check-spelling docs](https://docs.check-spelling.dev/).

## Implementation details

For full technical details about the spell checker, see:

- [check-spelling documentation](https://docs.check-spelling.dev/)
- [check-spelling GitHub repository](https://github.com/check-spelling/check-spelling)

The Keptn spell checker checks both documentation and code for spelling,
based on a set of dictionaries:

- We use general English language and technical terminology
StackScribe marked this conversation as resolved.
Show resolved Hide resolved
from dictionaries that are provided and maintained by check-spelling.
The configuration is specified in files in the
[.github/actions/spelling](https://github.com/keptn/lifecycle-toolkit/tree/main/.github/actions/spelling)
directory.
[expect.txt](https://github.com/keptn/lifecycle-toolkit/tree/main/.github/actions/spelling)
odubajDT marked this conversation as resolved.
Show resolved Hide resolved
lists Keptn terms for both documentation and code.
- We also use the specialized technical dictionaries provided by check-spelling
for Kubernetes and Go.
The dictionaries we use are specified in the
[.github/workflows/spell-checker.yml](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/workflows/spell-checker.yml)
file.

Check-spelling supports both American and British spelling
and both are allowed in the Keptn documentation.

Check-spelling provides dictionaries for a number of non-English languages
but we do not currently use those.

Note that Check-spelling does not check for proper capitalization of terms.
All dictionary terms are listed with lowercase letters.
Check-spelling recognizes capitalized versions of these words but,
if capitalized words are listed in a dictionary,
check-spelling rejects non-capitalized forms
which are common in code.
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,7 @@ nav:
- Contribution guidelines for documentation: docs/contribute/docs/contrib-guidelines-docs.md
- Build Documentation Locally: docs/contribute/docs/local-building.md
- Linter Requirements: docs/contribute/docs/linter-requirements.md
- Spell Checker: docs/contribute/docs/spell-check.md
- Source File Structure: docs/contribute/docs/source-file-structure.md
- Published Doc Structure: docs/contribute/docs/publish.md
- Word list: docs/contribute/docs/word-list.md
Expand Down
Loading