docs: configure spell check, minor improvements (#5369)

This PR configures the spell-check added to the docs workflow in the github-actions repo: FuelLabs/github-actions#23 The files checked are configured in `.spellcheck.yml`. This is also where you can configure what types of elements are ignored. Right now it ignores: - All code blocks that have a language (and will check code blocks that do not have a language) - Anything in between backticks - Words in `spell-check-custom-words.txt` (case sensitive, only exact match) - Numbers, even if they are attached to a word - Links in markdown link format #### Handling errors: If the 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`. --------- Co-authored-by: Sophie Dankel <[email protected]>
FuelLabs · Dec 19, 2023 · fe65ca4 · fe65ca4
1 parent be51106
commit fe65ca4
Show file tree

Hide file tree

Showing 58 changed files with 353 additions and 140 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -12,4 +12,5 @@ jobs:
   test:
     uses: FuelLabs/github-actions/.github/workflows/mdbook-docs.yml@master
     with:
-      docs-src-path: 'docs/book/src'
+      docs-src-path: 'docs/book/src'
+      spellcheck-config-path: 'docs/book/.spellcheck.yml'
diff --git a/docs/book/.spellcheck.yml b/docs/book/.spellcheck.yml
@@ -0,0 +1,28 @@
+matrix:
+  - name: SPCheck
+    aspell:
+      lang: en
+    dictionary:
+      encoding: utf-8
+      wordlists:
+        - docs/book/spell-check-custom-words.txt
+    pipeline:
+      - pyspelling.filters.context:
+          context_visible_first: true
+          escapes: \\[\\`~]
+          delimiters:
+          # Ignore all code blocks
+          - open: '(?s)^(?P<open> *`{3,}\s*(\w+\s*,?\s*)+.*?)$'
+            close: '^( *`{3,})$'
+      - pyspelling.filters.markdown:
+          markdown_extensions:
+            - pymdownx.superfences:
+      - pyspelling.filters.html:
+          comments: false
+          ignores:
+            - code
+            - pre
+    sources:
+      - '**/book/src/*.md'
+      - '**/book/src/**/*.md'
+    default_encoding: utf-8
diff --git a/docs/book/spell-check-custom-words.txt b/docs/book/spell-check-custom-words.txt
@@ -0,0 +1,187 @@
+ABI
+ABIs
+ASM
+IDE
+IDEs
+LSP
+namespace
+ALU
+APIs
+JSON
+BrowserStack
+CLI
+Deserialization
+deserializing
+DApp
+subcurrency
+Subcurrency
+intrinsics
+Intrinsics
+workspace
+workspaces
+Workspaces
+neovim
+EVM
+EVM's
+EOA
+ERC
+Ethereum
+Ethereum's
+FVM
+FuelVM
+Fuelup
+Github
+GraphQL
+Infura
+JSON
+LSP
+Merkle
+PoA
+PoS
+PoW
+RPC
+SDK
+SDK's
+SDKs
+SauceLabs
+Sepolia
+Structs
+Sway
+TAI
+TODO
+TypeScript
+UTF
+UTXO
+UTXOs
+Utils
+VM
+VSCode
+abigen
+args
+async
+backend
+backtraces
+blockchain
+blockchain's
+bytecode
+codespace
+codespaces
+config
+cryptographic
+customizable
+customizations
+dapp
+dev
+dropdown
+enum
+enums
+env
+forc
+frontend
+fuelup
+fullstack
+graphQL
+graphql
+http
+https
+js
+localhost
+mainnet
+mempool
+merkle
+monorepo
+monorepos
+natively
+npm
+nvm
+onboarding
+params
+pnpm
+prerelease
+queryable
+quickstart
+relayer
+relayers
+repo
+repos
+runnable
+stateful
+struct
+structs
+struct's
+testnet
+testnets
+toolchain
+toolchains
+urql
+validator
+validators
+superABI
+superABIs
+SuperABIs
+supertraits
+compositional
+typeclass
+turbofish
+DSL
+TOML
+IPFS
+Bitwise
+Bitwise
+runtime
+runtimes
+formatter
+deployable
+Utils
+ETH
+initializer
+initializers
+destructuring
+instantiation
+VMs
+superset
+CEI
+pre
+entrancy
+interoperable
+blockchains
+keccak
+SHA
+UI
+backtrace
+Collateralized
+collateralized
+submodule
+DEX
+TypeChain
+inlines
+inlining
+MiB
+FuelVM's
+deterministically
+CLI
+VS
+GraphViz
+DOT
+DCA
+AST
+GitHub
+decrypt
+subcommand
+subcommands
+Subcommands
+supertrait
+supertraits
+Supertraits
+incrementor
+monomorphization
+Booleans
+boolean
+Orchestrator
+orchestrator
+growable
+arity
+tuple's
+unary
+SRC
+DEX
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -10,7 +10,7 @@
 - [Examples](./examples/index.md)
   - [Counter](./examples/counter.md)
   - [Subcurrency](./examples/subcurrency.md)
-  - [FizzBuzz](./examples/fizzbuzz.md)
+  - [`FizzBuzz`](./examples/fizzbuzz.md)
   - [Wallet Smart Contract](./examples/wallet_smart_contract.md)
 - [Program Types](./sway-program-types/index.md)
   - [Contracts](./sway-program-types/smart_contracts.md)
@@ -69,28 +69,28 @@
   - [Workspaces](./forc/workspaces.md)
   - [Dependencies](./forc/dependencies.md)
   - [Commands](./forc/commands/index.md)
-    - [forc addr2line](./forc/commands/forc_addr2line.md)
-    - [forc build](./forc/commands/forc_build.md)
-    - [forc check](./forc/commands/forc_check.md)
-    - [forc clean](./forc/commands/forc_clean.md)
-    - [forc completions](./forc/commands/forc_completions.md)
-    - [forc contract-id](./forc/commands/forc_contract-id.md)
-    - [forc init](./forc/commands/forc_init.md)
-    - [forc new](./forc/commands/forc_new.md)
-    - [forc parse-bytecode](./forc/commands/forc_parse-bytecode.md)
-    - [forc plugins](./forc/commands/forc_plugins.md)
-    - [forc predicate-root](./forc/commands/forc_predicate-root.md)
-    - [forc test](./forc/commands/forc_test.md)
-    - [forc update](./forc/commands/forc_update.md)
-    - [forc template](./forc/commands/forc_template.md)
+    - [`forc addr2line`](./forc/commands/forc_addr2line.md)
+    - [`forc build`](./forc/commands/forc_build.md)
+    - [`forc check`](./forc/commands/forc_check.md)
+    - [`forc clean`](./forc/commands/forc_clean.md)
+    - [`forc completions`](./forc/commands/forc_completions.md)
+    - [`forc contract-id`](./forc/commands/forc_contract-id.md)
+    - [`forc init`](./forc/commands/forc_init.md)
+    - [`forc new`](./forc/commands/forc_new.md)
+    - [`forc parse-bytecode`](./forc/commands/forc_parse-bytecode.md)
+    - [`forc plugins`](./forc/commands/forc_plugins.md)
+    - [`forc predicate-root`](./forc/commands/forc_predicate-root.md)
+    - [`forc test`](./forc/commands/forc_test.md)
+    - [`forc update`](./forc/commands/forc_update.md)
+    - [`forc template`](./forc/commands/forc_template.md)
   - [Plugins](./forc/plugins/index.md)
-    - [forc client](./forc/plugins/forc_client/index.md)
-      - [forc deploy](./forc/plugins/forc_client/forc_deploy.md)
-      - [forc run](./forc/plugins/forc_client/forc_run.md)
-      - [forc submit](./forc/plugins/forc_client/forc_submit.md)
-    - [forc crypto](./forc/plugins/forc_crypto.md)
-    - [forc debug](./forc/plugins/forc_debug.md)    
-    - [forc doc](./forc/plugins/forc_doc.md)
-    - [forc explore](./forc/plugins/forc_explore.md)
-    - [forc fmt](./forc/plugins/forc_fmt.md)
-    - [forc lsp](./forc/plugins/forc_lsp.md)
+    - [`forc client`](./forc/plugins/forc_client/index.md)
+      - [`forc deploy`](./forc/plugins/forc_client/forc_deploy.md)
+      - [`forc run`](./forc/plugins/forc_client/forc_run.md)
+      - [`forc submit`](./forc/plugins/forc_client/forc_submit.md)
+    - [`forc crypto`](./forc/plugins/forc_crypto.md)
+    - [`forc debug`](./forc/plugins/forc_debug.md)
+    - [`forc doc`](./forc/plugins/forc_doc.md)
+    - [`forc explore`](./forc/plugins/forc_explore.md)
+    - [`forc fmt`](./forc/plugins/forc_fmt.md)
+    - [`forc lsp`](./forc/plugins/forc_lsp.md)
diff --git a/docs/book/src/advanced/assembly.md b/docs/book/src/advanced/assembly.md
@@ -1,10 +1,10 @@
 # Inline Assembly in Sway
 
-While many users will never have to touch assembly language while writing sway code, it is a powerful tool that enables many advanced use-cases (ie: optimizations, building libraries, etc).
+While many users will never have to touch assembly language while writing sway code, it is a powerful tool that enables many advanced use-cases (e.g., optimizations, building libraries, etc).
 
 ## ASM Block
 
-In Sway, the way we use assembly inline is to declare an asm block like this:
+In Sway, the way we use assembly inline is to declare an `asm` block like this:
 
 ```sway
 asm() {...}

diff --git a/docs/book/src/advanced/associated_types.md b/docs/book/src/advanced/associated_types.md
@@ -61,7 +61,7 @@ In this example, `get_value` is a trait method that returns an associated type `
 ## Use Cases
 
 Associated types are particularly useful in scenarios where you want to define traits that work with different
-types of data structures or abstractions, allowing the implementor to specify the concrete types. Some common use cases include:
+types of data structures or abstractions, allowing the implementer to specify the concrete types. Some common use cases include:
 
 - Collections: Traits for generic collections that allow users to specify the type of elements.
 - Iterator Patterns: Traits for implementing iterators with varying element types.

diff --git a/docs/book/src/advanced/traits.md b/docs/book/src/advanced/traits.md
@@ -20,7 +20,7 @@ We have just declared a trait called `Compare`. After the name of the trait, the
 
 ## Implementing a Trait
 
-Ok, so I know that numbers can be equal. I want to implement my `Compare` trait for `u64`. Let's take a look at how that is done:
+The example below implements a `Compare` trait for `u64` to check if two numbers are equal. Let's take a look at how that is done:
 
 ```sway
 impl Compare for u64 {
@@ -34,8 +34,8 @@ The above snippet declares all of the methods in the trait `Compare` for the typ
 
 ## Supertraits
 
-When using multiple traits, scenarios often come up where one trait may require functionality from another trait. This is where supertraits come in as they allow you to require a trait when implementing another
-trait (ie. a trait with a trait). A good example of this is the `Ord` trait of the `core` library of Sway. The `Ord` trait requires the `Eq` trait, so `Eq` is kept as a separate trait as one may decide to implement `Eq`
+When using multiple traits, scenarios often come up where one trait may require functionality from another trait. This is where supertraits come in as they allow you to require a trait when implementing another trait, i.e., a trait with a trait.
+A good example of this is the `Ord` trait of the `core` library of Sway. The `Ord` trait requires the `Eq` trait, so `Eq` is kept as a separate trait as one may decide to implement `Eq`
 without implementing other parts of the `Ord` trait.
 
 ```sway

diff --git a/docs/book/src/basics/blockchain_types.md b/docs/book/src/basics/blockchain_types.md
@@ -54,7 +54,7 @@ let forty_two: b256 = my_contract_id.into();
 
 <!-- This section should explain the `Identity` type -->
 <!-- identity:example:start -->
-The `Identity` type is an enum that allows for the handling of both `Address` and `ContractId` types. This is useful in cases where either type is accepted, e.g. receiving funds from an identified sender, but not caring if the sender is an address or a contract.
+The `Identity` type is an enum that allows for the handling of both `Address` and `ContractId` types. This is useful in cases where either type is accepted, e.g., receiving funds from an identified sender, but not caring if the sender is an address or a contract.
 <!-- identity:example:end -->
 
 An `Identity` is implemented as follows.

diff --git a/docs/book/src/basics/built_in_types.md b/docs/book/src/basics/built_in_types.md
@@ -52,7 +52,7 @@ computation gets reverted automatically by FuelVM.
 additional overflow/underflow checks inserted, which generally results in
 somewhat higher gas consumption.
 
-The same does not happen with 256-bit operations, including `b256`, which uses specialized operations and are as performant as possible.
+The same does not happen with 256-bit operations, including `b256`, which uses specialized operations and are as efficient as possible.
 <!-- default_num:example:end -->
 
 ## Boolean Type
@@ -82,7 +82,7 @@ In Sway, string literals are stored as variable length string slices. Which mean
 let my_string: str = "fuel";
 ```
 
-String slices, because they contain pointers have limited usage. They cannot be used is constants, storages, configurables, nor as main function argument or returns.
+String slices, because they contain pointers, have limited usage. They cannot be used in constants, storage, configurable constants, nor as main function arguments or returns.
 
 For these cases one must use string arrays, as described below.
 
@@ -174,7 +174,7 @@ let x = [1, 2, 3, 4, 5];
 <!-- array_details:example:start -->
 Arrays are allocated on the stack since their size is known. An array's size is _always_ static, i.e. it cannot change. An array of five elements cannot become an array of six elements.
 
-Arrays can be iterated over, unlike tuples. An array's type is written as the type the array contains followed by the number of elements, semicolon-separated and within square brackets, e.g. `[u64; 5]`. To access an element in an array, use the _array indexing syntax_, i.e. square brackets.
+Arrays can be iterated over, unlike tuples. An array's type is written as the type the array contains followed by the number of elements, semicolon-separated and within square brackets, e.g., `[u64; 5]`. To access an element in an array, use the _array indexing syntax_, i.e. square brackets.
 <!-- array_details:example:end -->
 
 Array elements can also be mutated if the underlying array is declared as mutable:

diff --git a/docs/book/src/basics/constants.md b/docs/book/src/basics/constants.md
@@ -46,7 +46,7 @@ The identifier is the name of the constant used in the path. The type is the typ
 definition has to implement.
 <!-- assoc_constants:example:end -->
 
-You can _define_ an associated const directly in the interface surface of a trait:
+You can _define_ an associated `const` directly in the interface surface of a trait:
 
 ```sway
 script;

diff --git a/docs/book/src/basics/index.md b/docs/book/src/basics/index.md
@@ -1,6 +1,6 @@
 # Sway Language basics
 
-Sway is a programming language designed for the FuelVM. It is a statically typed, compiled language with type inference and traits. Sway aims to make smart contract development safer and more performant through the use of strong static analysis and compiler feedback.
+Sway is a programming language designed for the FuelVM. It is a statically typed, compiled language with type inference and traits. Sway aims to make smart contract development safer and more efficient through the use of strong static analysis and compiler feedback.
 
 Get started with the basics of Sway:
 

diff --git a/docs/book/src/basics/methods_and_associated_functions.md b/docs/book/src/basics/methods_and_associated_functions.md
@@ -6,7 +6,7 @@ Methods are similar to functions in that we declare them with the `fn` keyword a
 
 _Associated functions_ are very similar to _methods_, in that they are also defined in the context of a struct or enum, but they do not actually use any of the data in the struct and as a result do not take _self_ as a parameter. Associated functions could be standalone functions, but they are included in a specific type for organizational or semantic reasons.
 
-To declare methods and associated functions for a struct or enum, use an _impl block_. Here, `impl` stands for implementation.
+To declare methods and associated functions for a struct or enum, use an `impl` block. Here, `impl` is short for implementation.
 <!-- methods_af:example:end -->
 
 ```sway