Ignore code in the spellcheck workflow #46191

ptgott · 2024-09-03T19:11:59Z

Applies To

The spellcheck workflow that docs changes must pass before we can merge them.

Details

The spellcheck workflow has become unwieldy. The workflow checks all words in a docs page, including those in code snippets. This means that we need to configure the workflow to ignore spellings that would be incorrect in regular paragraphs in order to allow these spellings within code snippets. As a result, the list of ignored words has become long and difficult to manage.

How will we know this is resolved?

Find a way to ignore code snippets in the spellcheck workflow. The vale linter, which we also use in the docs, has a built-in spell checker, and we can configure the spell checker to check only certain scopes, such as paragraphs, headings, and lists, ignoring code snippets.

Note that the vale linter also skips link references, avoiding another issue we have with the current cspell workflow.

Related Issues

Teleport Operator reference docs contain a large number of internal link references that fail the spell checker. Until we find a more scalable spell check workflow (#46191), ignore these reference docs in the spell checker.

Backports #46259 Teleport Operator reference docs contain a large number of internal link references that fail the spell checker. Until we find a more scalable spell check workflow (#46191), ignore these reference docs in the spell checker.

* Auto-generate operator CRD docs Backports #44107 * Auto-generate operator CRD docs We already pull JSON schema data from Teleport protobuf message definitions in order to generate CRD manifests. Extract a shared library from code within the existing protoc plugin for generating CRDs. This way, we can use the library to generate docs for our CRDs with a separate plugin, and don't need to complicate the interface for using the existing plugin. - Organize `integrations/crdgen` into `lib` and `cmd` directories, turning `lib` into a package. - Edit the `generateSchema` signature to include a function that formats a CRD into a document, injecting separate functions for formatting the CRD as YAML and as a docs page. - Add Makefile targets for building the docs plugin and generating CRD docs. To display the resulting reference pages in the docs, this change configures `docs/config.json` to generate the Reference section of the sidebar from the docs directory. This requires moving the Helm reference includes directory into `docs/pages/includes`. * Respond to hugoShaka feedback - Do not display the `status` field. - Indicate that enum fields can take an integer or a string. This is consistent with our comment conventions, which describe both the integer and the string values for each enum option. * Sort CRD reference page sections Also handle duplicate page sections by including the names of parent properties within section headings. * Fix crdgen Makefile targets - bring test data and hack out of `lib/` - fix broken debug builds - add crd-docs checks to the `crds-up-to-date` target - trigger proto lint on CRD and CRD doc changes - removed stale gitkeep in `docs/pages/includes/crd-docs/.gitkeep` - split crdgen formatting logic in another file for readability - update license header years on new files * fixup! Fix crdgen Makefile targets * lint files due to false positive 'generated' comment * fixup! lint files due to false positive 'generated' comment * Incorporate rosstimothy feedback Remove an unnecessary package. Also regenerate the CRD docs. * fix debug builds and gitignore * fixup! fix debug builds and gitignore * Respond to rosstimothy feedback Fix integrations/operator/crdgen/Makefile * Fix spelling * Fix flaky propertyTable test Compare the unsorted slice elements, since sorting takes place on the containing VersionSection. --------- Co-authored-by: hugoShaka <hugo.hervieux@goteleport.com> * Ignore Operator references in the spellcheck Backports #46259 Teleport Operator reference docs contain a large number of internal link references that fail the spell checker. Until we find a more scalable spell check workflow (#46191), ignore these reference docs in the spell checker. * Update Operator docs * Fix lint error --------- Co-authored-by: hugoShaka <hugo.hervieux@goteleport.com>

Related to #46191 Help us to move to a new, more scalable spell checker based on vale by supporting spell checking in the Operator resource reference. While `vale` cannot ignore specific files (unless we run the CLI on all _but_ those files), it is possible to fine-tune a vale spell-check rule so we can check the Operator resource reference: - Fix specific spelling errors in some of our proto files. - Use "Boolean" instead of "boolean" in Operator resource reference docs by substituting the incorrect spelling in the docs generator. - Wrap type names in backticks to avoid the vale spell checker. The vale spell checker ignores all content in backticks.

Related to #46191 Help us to move to a new, more scalable spell checker based on vale by supporting spell checking in the Operator resource reference. While vale cannot ignore specific files (unless we run the CLI on all _but_ those files), it is possible to fine-tune a vale spell-check rule so we can check the Operator resource reference: - Fix specific spelling errors in some of our proto files. - Use "Boolean" instead of "boolean" in Operator resource reference docs by substituting the incorrect spelling in the docs generator. - Wrap type names in backticks to avoid the vale spell checker. The vale spell checker ignores all content in backticks.

Related to #46191 Help us to move to a new, more scalable spell checker based on vale by supporting spell checking in the Operator resource reference. While vale cannot ignore specific files (unless we run the CLI on all _but_ those files), it is possible to fine-tune a vale spell-check rule so we can check the Operator resource reference: - Fix specific spelling errors in some of our proto files. - Use "Boolean" instead of "boolean" in Operator resource reference docs by substituting the incorrect spelling in the docs generator. - Wrap type names and headings in backticks to avoid the vale spell checker. The vale spell checker ignores all content in backticks.

Related to #46191 Help us move to a new, more scalable spell checker based on vale by supporting spell checking in the Operator resource reference. While vale cannot ignore specific files (unless we run the CLI on all _but_ those files), it is possible to fine-tune a vale spell-check rule so we can check the Operator resource reference docs: - Fix specific spelling errors in some of our proto files. - Use "Boolean" instead of "boolean" in Operator resource reference docs by substituting the incorrect spelling in the docs generator. - Wrap field type names and headings in backticks to avoid the vale spell checker. The vale spell checker ignores all content in backticks.

Related to #46191 Help us move to a new, more scalable spell checker based on vale by fixing spelling errors in the Terraform provider resource reference docs. This change fixes the spelling in the protobuf messages that these docs are based on.

Related to #46191 Help us move to a new, more scalable spell checker based on vale by fixing spelling errors in the Terraform provider resource reference docs. This change fixes the spelling in the protobuf messages that these docs are based on. Since the vale checker ignores words in backticks, this change wraps field/value names that would otherwise fail the spell checker in backticks.

Closes #46191 This change adds a Vale spelling rule that replaces the current cspell workflow. The Vale spelling rule ignores spelling errors in code-style text by default, and includes more configuration options for filtering spelling errors. This also allows us to reduce the number of linting workflows. This change also adds a file containing words to ignore in the spellcheck rule, based on the current `cspell.json`. While this change introduces new spelling errors, we can remove these incrementally, since the Vale spellchecker only flags issues in files changed by a PR. This change also configures the Vale spellcheck rule to ignore abbreviations. For consistency with the cspell configuration, this change ignores spelling errors in Terraform and Kubernetes operator reference pages. To do so, it adds the `{/* vale spelling.spelling = OFF */}` comment directive in relevant auto-generated reference pages.

ptgott added the documentation label Sep 3, 2024

ptgott self-assigned this Sep 4, 2024

ptgott mentioned this issue Sep 4, 2024

Ignore Operator references in the spellcheck #46259

Merged

ptgott mentioned this issue Sep 23, 2024

Fix spelling in Operator docs and related protos #46876

Closed

ptgott mentioned this issue Sep 23, 2024

Fix spelling in TF docs and related protos #46878

Closed

ptgott linked a pull request Oct 25, 2024 that will close this issue

Add a Vale spelling rule #47970

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Ignore code in the spellcheck workflow #46191

Ignore code in the spellcheck workflow #46191

ptgott commented Sep 3, 2024 •

edited

Loading

Ignore code in the spellcheck workflow #46191

Ignore code in the spellcheck workflow #46191

Comments

ptgott commented Sep 3, 2024 • edited Loading

Applies To

Details

How will we know this is resolved?

Related Issues

ptgott commented Sep 3, 2024 •

edited

Loading