From 353c07c883a6006d10f496ee0b9d7055cc98adff Mon Sep 17 00:00:00 2001 From: sarahschwartz <58856580+sarahschwartz@users.noreply.github.com> Date: Wed, 22 Nov 2023 13:51:52 -0700 Subject: [PATCH 1/6] add next spell-check --- .github/workflows/next-docs.yml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.github/workflows/next-docs.yml b/.github/workflows/next-docs.yml index b0cfcc1..f4bd2fd 100644 --- 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 folder 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/spellcheck-github-actions@0.34.0 + name: Spellcheck + with: + config_path: ${{ inputs.spellcheck-config-path }} + task_name: SPCheck + check-doc-folders: name: Check Configs, Components, & Folders runs-on: ubuntu-latest From 833cb07bd09ce1687e8ccfc50a44283599885eb3 Mon Sep 17 00:00:00 2001 From: sarahschwartz <58856580+sarahschwartz@users.noreply.github.com> Date: Wed, 22 Nov 2023 15:57:12 -0700 Subject: [PATCH 2/6] spell check mdbook & vp docs --- .github/workflows/mdbook-docs.yml | 15 +++++++++++++++ .github/workflows/next-docs.yml | 2 +- .github/workflows/vp-docs.yml | 15 +++++++++++++++ 3 files changed, 31 insertions(+), 1 deletion(-) diff --git a/.github/workflows/mdbook-docs.yml b/.github/workflows/mdbook-docs.yml index f61e776..799fde1 100644 --- a/.github/workflows/mdbook-docs.yml +++ b/.github/workflows/mdbook-docs.yml @@ -12,8 +12,23 @@ on: required: false type: string default: '' + 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/spellcheck-github-actions@0.34.0 + name: Spellcheck + with: + config_path: ${{ inputs.spellcheck-config-path }} + task_name: SPCheck + markdown-link-check: name: Check Links runs-on: ubuntu-latest diff --git a/.github/workflows/next-docs.yml b/.github/workflows/next-docs.yml index f4bd2fd..a20dbd2 100644 --- a/.github/workflows/next-docs.yml +++ b/.github/workflows/next-docs.yml @@ -12,7 +12,7 @@ on: required: true type: string spellcheck-config-path: - description: "the folder where the .spellcheck.yml file lives" + description: "the path where the .spellcheck.yml file lives" required: true type: string diff --git a/.github/workflows/vp-docs.yml b/.github/workflows/vp-docs.yml index ad0dd7f..ff2a165 100644 --- 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/spellcheck-github-actions@0.34.0 + name: Spellcheck + with: + config_path: ${{ inputs.spellcheck-config-path }} + task_name: SPCheck + check-doc-folders: name: Check Configs & Folders runs-on: ubuntu-latest From 6af5167e13e59810836ba81c46b41061eb99350d Mon Sep 17 00:00:00 2001 From: sarahschwartz <58856580+sarahschwartz@users.noreply.github.com> Date: Wed, 22 Nov 2023 16:29:11 -0700 Subject: [PATCH 3/6] reorder --- .github/workflows/mdbook-docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/mdbook-docs.yml b/.github/workflows/mdbook-docs.yml index 799fde1..8cad05b 100644 --- a/.github/workflows/mdbook-docs.yml +++ b/.github/workflows/mdbook-docs.yml @@ -7,15 +7,15 @@ 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 type: string default: '' - spellcheck-config-path: - description: "the path where the .spellcheck.yml file lives" - required: true - type: string jobs: spell-check: From e4eb1df6677b253429f141b20a3edea91cc89bed Mon Sep 17 00:00:00 2001 From: sarahschwartz <58856580+sarahschwartz@users.noreply.github.com> Date: Wed, 22 Nov 2023 17:04:49 -0700 Subject: [PATCH 4/6] test --- .github/workflows/mdbook-docs.yml | 60 ------------------------------- 1 file changed, 60 deletions(-) diff --git a/.github/workflows/mdbook-docs.yml b/.github/workflows/mdbook-docs.yml index 8cad05b..89513aa 100644 --- a/.github/workflows/mdbook-docs.yml +++ b/.github/workflows/mdbook-docs.yml @@ -28,63 +28,3 @@ jobs: with: config_path: ${{ inputs.spellcheck-config-path }} task_name: SPCheck - - markdown-link-check: - name: Check Links - runs-on: ubuntu-latest - steps: - - name: Checkout repo - uses: actions/checkout@v3 - - name: Checkout repo2 - uses: actions/checkout@v3 - with: - repository: 'FuelLabs/github-actions' - path: 'workflow' - - name: Run pre-command - if: inputs.pre-command != '' - run: ${{ inputs.pre-command }} - - uses: gaurav-nelson/github-action-markdown-link-check@1.0.12 - with: - config-file: 'workflow/docs-hub/mlc.mdbook.json' - - markdown-lint: - name: Markdown Lint - runs-on: ubuntu-latest - steps: - - name: Checkout repo - uses: actions/checkout@v3 - - name: Checkout repo2 - uses: actions/checkout@v3 - with: - repository: 'FuelLabs/github-actions' - path: 'workflow' - - name: Run pre-command - if: inputs.pre-command != '' - run: ${{ inputs.pre-command }} - - uses: actions/setup-node@v3 - with: - node-version: 18 - - run: | - npm install -g markdownlint-cli@0.32.1 - 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 - steps: - - name: Checkout repo - uses: actions/checkout@v3 - - name: Checkout repo2 - uses: actions/checkout@v3 - with: - repository: 'FuelLabs/github-actions' - path: 'workflow' - - name: Run pre-command - if: inputs.pre-command != '' - run: ${{ inputs.pre-command }} - - name: Setup node - uses: actions/setup-node@v3 - with: - node-version: 18 - - name: Run script - run: node workflow/docs-hub/mdbook-docs.js ${{ inputs.docs-src-path }} From e396308d5ded476c521d7936a9bff99f9d775791 Mon Sep 17 00:00:00 2001 From: sarahschwartz <58856580+sarahschwartz@users.noreply.github.com> Date: Tue, 5 Dec 2023 11:30:21 -0700 Subject: [PATCH 5/6] add mdbooks CI back --- .github/workflows/mdbook-docs.yml | 60 +++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/.github/workflows/mdbook-docs.yml b/.github/workflows/mdbook-docs.yml index 89513aa..de16783 100644 --- a/.github/workflows/mdbook-docs.yml +++ b/.github/workflows/mdbook-docs.yml @@ -18,6 +18,66 @@ on: default: '' jobs: + markdown-link-check: + name: Check Links + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v3 + - name: Checkout repo2 + uses: actions/checkout@v3 + with: + repository: 'FuelLabs/github-actions' + path: 'workflow' + - name: Run pre-command + if: inputs.pre-command != '' + run: ${{ inputs.pre-command }} + - uses: gaurav-nelson/github-action-markdown-link-check@1.0.12 + with: + config-file: 'workflow/docs-hub/mlc.mdbook.json' + + markdown-lint: + name: Markdown Lint + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v3 + - name: Checkout repo2 + uses: actions/checkout@v3 + with: + repository: 'FuelLabs/github-actions' + path: 'workflow' + - name: Run pre-command + if: inputs.pre-command != '' + run: ${{ inputs.pre-command }} + - uses: actions/setup-node@v3 + with: + node-version: 18 + - run: | + npm install -g markdownlint-cli@0.32.1 + 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 + steps: + - name: Checkout repo + uses: actions/checkout@v3 + - name: Checkout repo2 + uses: actions/checkout@v3 + with: + repository: 'FuelLabs/github-actions' + path: 'workflow' + - name: Run pre-command + if: inputs.pre-command != '' + run: ${{ inputs.pre-command }} + - name: Setup node + uses: actions/setup-node@v3 + with: + 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: From 377a56f89a100f61b3f1a73a74ba47db4f39e838 Mon Sep 17 00:00:00 2001 From: sarahschwartz <58856580+sarahschwartz@users.noreply.github.com> Date: Thu, 7 Dec 2023 11:55:30 -0700 Subject: [PATCH 6/6] update docs tests README, pre-command for spell-check --- .github/workflows/mdbook-docs.yml | 3 +++ docs-hub/README.md | 40 ++++++++++++++++++++++++------- 2 files changed, 35 insertions(+), 8 deletions(-) diff --git a/.github/workflows/mdbook-docs.yml b/.github/workflows/mdbook-docs.yml index de16783..21b3c51 100644 --- a/.github/workflows/mdbook-docs.yml +++ b/.github/workflows/mdbook-docs.yml @@ -83,6 +83,9 @@ jobs: steps: - name: Checkout Code uses: actions/checkout@v3 + - name: Run pre-command + if: inputs.pre-command != '' + run: ${{ inputs.pre-command }} - uses: rojopolis/spellcheck-github-actions@0.34.0 name: Spellcheck with: diff --git a/docs-hub/README.md b/docs-hub/README.md index 3e9f479..41f521a 100644 --- a/docs-hub/README.md +++ b/docs-hub/README.md @@ -16,6 +16,9 @@ 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 @@ -23,6 +26,8 @@ with: | 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,6 +126,7 @@ 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 @@ -124,6 +134,7 @@ with: | 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). \ No newline at end of file +The primary license for this repo is `Apache 2.0`, see [`LICENSE`](../LICENSE.md).