docs: add spell-check (#23)

This PR adds a spell-check to each docs workflow. You can see it tested here: Sway: FuelLabs/sway#5369 Fuelup: FuelLabs/fuelup#535 Specs: FuelLabs/fuel-specs#539 Fuels-rs: FuelLabs/fuels-rs#1224 Fuels-ts: FuelLabs/fuels-ts#1484 Wallet: FuelLabs/fuels-wallet#987 Indexer: FuelLabs/fuel-indexer#1496 GraphQL: FuelLabs/fuel-graphql-docs#25
FuelLabs · Dec 7, 2023 · a7b52d4 · a7b52d4
1 parent e7af195
commit a7b52d4
Show file tree

Hide file tree

Showing 4 changed files with 81 additions and 9 deletions.
diff --git a/.github/workflows/mdbook-docs.yml b/.github/workflows/mdbook-docs.yml
@@ -7,6 +7,10 @@ on:
         description: "the folder where SUMMARY.md lives"
         required: true
         type: string
+      spellcheck-config-path:
+        description: "the path where the .spellcheck.yml file lives"
+        required: true
+        type: string
       pre-command:
         description: "a command to run before the jobs"
         required: false
@@ -52,7 +56,7 @@ jobs:
       - run: |
           npm install -g [email protected]
           markdownlint --config workflow/docs-hub/.markdownlint.yaml --ignore-path workflow/docs-hub/.markdownlintignore '**/*.md'
-  
+
   check-doc-folders:
     name: Check SUMMARY & Folders
     runs-on: ubuntu-latest
@@ -73,3 +77,17 @@ jobs:
           node-version: 18
       - name: Run script
         run: node workflow/docs-hub/mdbook-docs.js ${{ inputs.docs-src-path }}
+
+  spell-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+      - name: Run pre-command
+        if: inputs.pre-command != ''
+        run: ${{ inputs.pre-command }}
+      - uses: rojopolis/[email protected]
+        name: Spellcheck
+        with:
+          config_path: ${{ inputs.spellcheck-config-path }}
+          task_name: SPCheck
diff --git a/.github/workflows/next-docs.yml b/.github/workflows/next-docs.yml
@@ -11,8 +11,23 @@ on:
         description: "the src folder where the nav.json and components.json files live"
         required: true
         type: string
+      spellcheck-config-path:
+        description: "the path where the .spellcheck.yml file lives"
+        required: true
+        type: string
 
 jobs: 
+  spell-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+      - uses: rojopolis/[email protected]
+        name: Spellcheck
+        with:
+          config_path: ${{ inputs.spellcheck-config-path }}
+          task_name: SPCheck
+
   check-doc-folders:
     name: Check Configs, Components, & Folders
     runs-on: ubuntu-latest

diff --git a/.github/workflows/vp-docs.yml b/.github/workflows/vp-docs.yml
@@ -7,8 +7,23 @@ on:
         description: "the folder path where the markdown files live"
         required: true
         type: string
+      spellcheck-config-path:
+        description: "the path where the .spellcheck.yml file lives"
+        required: true
+        type: string
 
 jobs: 
+  spell-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+      - uses: rojopolis/[email protected]
+        name: Spellcheck
+        with:
+          config_path: ${{ inputs.spellcheck-config-path }}
+          task_name: SPCheck
+
   check-doc-folders:
     name: Check Configs & Folders
     runs-on: ubuntu-latest

diff --git a/docs-hub/README.md b/docs-hub/README.md
@@ -16,13 +16,18 @@ The types of doc architectures that are supported in the docs hub are:
 uses: FuelLabs/github-actions/.github/workflows/mdbook-docs.yml@master
 with:
     docs-src-path: 'docs/book/src'
+    spellcheck-config-path: 'docs/book/.spellcheck.yml'
+    # OPTIONAL
+    pre-command: 'cargo run --package versions-replacer'
 ```
 
 ### Inputs
 
 | Name         | Description  |
 | ------------ | ------------ |
 | docs-src-path | the folder where SUMMARY.md lives |
+| spellcheck-config-path | the path for the spellcheck config file |
+| pre-command | optional: command to run before other checks |
 
 ### Outputs
 
@@ -34,11 +39,12 @@ This workflow:
 
 1. Runs a link check on all links found in markdown files. You can add regex patterns to ignore certain types of links in the [mlc.mdbook.json](mlc.mdbook.json) config file.
 2. Runs a lint check on all markdown files except those listed in the [.markdownlintignore](.markdownlintignore) file. It uses the configuration in [.markdownlint.yaml](.markdownlint.yaml).
-3. Checks for an index.md file in the docs src folder (and for the sway repo, in the generated forc docs folder). 
+3. Checks for an index.md file in the docs src folder (and for the sway repo, in the generated forc docs folder).
 4. Checks for to make sure there are no nested subfolders (except for those already accounted for in the generated forc docs).
 5. Checks to make sure the folder structure matches the SUMMARY navigation.
 6. Checks for unused files missing from the SUMMARY.
-7. Checks to see if a navigation order can be successfully generated from the SUMMARY. 
+7. Checks to see if a navigation order can be successfully generated from the SUMMARY.
+8. Runs a spell check using the configuration file at `spellcheck-config-path`.
 
 ## Next
 
@@ -51,6 +57,7 @@ uses: FuelLabs/github-actions/.github/workflows/next-docs.yml@master
 with:
     doc-folder-path: 'docs'
     src-folder-path: 'src'
+    spellcheck-config-path: 'docs/.spellcheck.yml'
 ```
 
 #### Links
@@ -79,6 +86,7 @@ jobs:
 | ------------ | ------------ |
 | doc-folder-path | the folder path where the mdx files live |
 | src-folder-path | the src folder where the nav.json and components.json files live |
+| spellcheck-config-path | the path for the spellcheck config file |
 
 #### Links
 
@@ -104,6 +112,7 @@ This workflow:
 4. Checks to make sure the names of components used in MDX files match the file name.
 5. Checks to make sure MDX components aren't nested more than twice. For example, `Examples.Events.Connect` & `Examples.Connect` are ok
 `Examples.Events.Connect.First` is not ok.
+6. Runs a spell check using the configuration file at `spellcheck-config-path`.
 
 #### Links
 
@@ -117,13 +126,15 @@ This workflow checks all links in mdx files.
 uses: FuelLabs/github-actions/.github/workflows/vp-docs.yml@master
 with:
     doc-folder-path: 'apps/docs/src'
+    spellcheck-config-path: 'apps/docs/book/.spellcheck.yml'
 ```
 
 ### Inputs
 
 | Name         | Description  |
 | ------------ | ------------ |
 | doc-folder-path | the folder path where the markdown files live |
+| spellcheck-config-path | the path for the spellcheck config file |
 
 ### Outputs
 
@@ -133,12 +144,25 @@ No outputs defined
 
 This workflow:
 
-1. Checks for an index.md file in the docs src folder. 
-4. Checks for to make sure there are no nested subfolders (except for those already accounted for in `api` and `guide` folders).
-5. Checks to make sure the file & folder names match what is in the config navigation.
-6. Checks for unused files missing from the config.
-7. Checks to see if a navigation order can be successfully generated from the config.
+1. Checks for an index.md file in the docs src folder.
+2. Checks for to make sure there are no nested subfolders (except for those already accounted for in `api` and `guide` folders).
+3. Checks to make sure the file & folder names match what is in the config navigation.
+4. Checks for unused files missing from the config.
+5. Checks to see if a navigation order can be successfully generated from the config.
+6. Runs a spell check using the configuration file at `spellcheck-config-path`.
+
+## Handling Spell Check Errors
+
+The files checked are configured in `.spellcheck.yml`.  This is also where you can configure what types of elements are ignored.
+
+If the spell check test fails:
+
+- look up the word in the question to verify it is a real word and is correctly spelled
+- If it is a file name or is code, use backticks to ignore the word.
+- If it is a real word that is spelled correctly, or an acronym that is either common or is defined already, add it to `spell-check-custom-words.txt`.
+- If needed, rewrite the sentence. Ex: DON'T use  "`lock`ing" and add "ing" to the custom words list. Instead, rewrite the sentence as "locking with the `lock` method".
+- If it otherwise should be ignored, you can configure the pipeline in `.spellcheck.yml`.
 
 ## License
 
-The primary license for this repo is `Apache 2.0`, see [`LICENSE`](../LICENSE.md).
+The primary license for this repo is `Apache 2.0`, see [`LICENSE`](../LICENSE.md).