From 152774c05d72af92502b71dd67003ea0d490c8d7 Mon Sep 17 00:00:00 2001 From: Sarah Schwartz <58856580+sarahschwartz@users.noreply.github.com> Date: Fri, 8 Dec 2023 08:03:42 -0700 Subject: [PATCH] docs: configure spell-check (#535) * fix spelling, test spell-checker * use master for docs CI --- .github/workflows/docs.yml | 1 + docs/.spellcheck.yml | 29 +++ docs/spell-check-custom-words.txt | 230 ++++++++++++++++++ docs/src/concepts/channels.md | 14 +- docs/src/concepts/how_fuelup_works.md | 4 +- docs/src/concepts/toolchains.md | 4 +- docs/src/configuration.md | 4 +- docs/src/developer_guide/adding_components.md | 2 +- .../src/developer_guide/building_a_channel.md | 14 +- docs/src/index.md | 3 +- docs/src/installation/other.md | 3 +- docs/src/overrides.md | 6 +- 12 files changed, 286 insertions(+), 28 deletions(-) create mode 100644 docs/.spellcheck.yml create mode 100644 docs/spell-check-custom-words.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 376f5c7ac..874f877b9 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -13,3 +13,4 @@ jobs: uses: FuelLabs/github-actions/.github/workflows/mdbook-docs.yml@master with: docs-src-path: 'docs/src' + spellcheck-config-path: 'docs/.spellcheck.yml' diff --git a/docs/.spellcheck.yml b/docs/.spellcheck.yml new file mode 100644 index 000000000..7ca30eed3 --- /dev/null +++ b/docs/.spellcheck.yml @@ -0,0 +1,29 @@ +matrix: + - name: SPCheck + aspell: + lang: en + dictionary: + encoding: utf-8 + wordlists: + - docs/spell-check-custom-words.txt + pipeline: + - pyspelling.filters.context: + context_visible_first: true + escapes: \\[\\`~] + delimiters: + # Ignore all code blocks + - open: '(?s)^(?P *`{3,}\s*(\w+\s*,?\s*)+.*?)$' + close: '^( *`{3,})$' + - pyspelling.filters.markdown: + markdown_extensions: + - pymdownx.superfences: + - pyspelling.filters.html: + comments: false + ignores: + - code + - pre + sources: + - 'docs/src/*.md' + - 'docs/src/**/*.md' + default_encoding: utf-8 + \ No newline at end of file diff --git a/docs/spell-check-custom-words.txt b/docs/spell-check-custom-words.txt new file mode 100644 index 000000000..915107e15 --- /dev/null +++ b/docs/spell-check-custom-words.txt @@ -0,0 +1,230 @@ +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 +FuelLabs +PRs +codebase +PostgreSQL +Postgres +MacOS +macOS +backends +hoc +semver +SQLx +Homebrew +Changelog +lookups +namespaces +YAML +WASM +WebAssembly +dApp +dApps +JWT +Schemas +schemas +AssemblyScript +indexable +Macbook +Dockerized +TLDR +IaaS +Updatable +SemVer +executables +unarchive +reproducibility +PowerShell +ZSH +Zsh +distributable +symlinks +installable +modularly +changelog +Fuelup's \ No newline at end of file diff --git a/docs/src/concepts/channels.md b/docs/src/concepts/channels.md index c0aa3b9c7..381733e32 100644 --- a/docs/src/concepts/channels.md +++ b/docs/src/concepts/channels.md @@ -30,7 +30,7 @@ The `nightly` channel is a published TOML file describing successful builds of t These builds are released in the [sway-nightly-binaries] repository and the workflows in that repo start building them every day at **00:00 UTC**. The `nightly` channel within `fuelup` is updated by a scheduled GitHub workflow that **runs every day at 01:00 UTC**, after builds have finished. -Note that nightlies might fail to build, in which case it is possible that the `nightly` toolchain may not be available for that day. +Note that the `nightly` channel might fail to build, in which case it is possible that the `nightly` toolchain may not be available for that day. You should use `nightly` if you want the latest changes to `master` that have not been officially released yet. Keep in mind that compatibility between `forc` and `fuel-core` is not guaranteed here, and you should expect unstable features to break. @@ -55,19 +55,19 @@ The `latest` channel is pointing to our latest beta network. This toolchain shou > > Reading the information below is only really necessary if you wish to contribute to the workflows or want a deeper understanding on how channels are updated. -The entrypoint of the scheduled workflow is within `index-versions.yml`. We run the Rust script `compare-versions` to collect versions of `forc` and `fuel-core` to be tested. These versions are filtered for incompatible versions prior to being used as a JSON string input to `test-toolchain-compatibility.yml`, where the testing occurs. +The entry point of the scheduled workflow is within `index-versions.yml`. We run the Rust script `compare-versions` to collect versions of `forc` and `fuel-core` to be tested. These versions are filtered for incompatible versions prior to being used as a JSON string input to `test-toolchain-compatibility.yml`, where the testing occurs. -In `test-toolchain-compatibility.yml`, The versions JSON string input is used to init a matrix using the [fromJSON](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson) expression. We checkout the Sway repo at the given `forc` version and pull the `fuel-core` Docker image at the given `fuel-core` version and run integration tests found in the [Sway CI](https://github.com/FuelLabs/sway/blob/3bd8eaf4a0f11a3009c9421100cc06c2e897b6c2/.github/workflows/ci.yml#L229-L270) for them. +In `test-toolchain-compatibility.yml`, The versions JSON string input is used to initialize a matrix using the [`fromJSON`](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson) expression. We checkout the Sway repo at the given `forc` version and pull the `fuel-core` Docker image at the given `fuel-core` version and run integration tests found in the [Sway CI](https://github.com/FuelLabs/sway/blob/3bd8eaf4a0f11a3009c9421100cc06c2e897b6c2/.github/workflows/ci.yml#L229-L270) for them. -Note that we only mark versions as incompatible specifically if tests fail, and not if other prior steps fail (eg. we do not want to mark versions as incompatible if there were errors pulling the Docker image) +Note that we only mark versions as incompatible specifically if tests fail, and not if other prior steps fail (e.g. we do not want to mark versions as incompatible if there were errors pulling the Docker image) The [upload-artifact](https://github.com/actions/upload-artifact) action is used to collect the test results from the matrix to be used later in a [download-artifact](https://github.com/actions/download-artifact) step. If tests were not skipped and are now done, we finally get to the `index-versions` job. We download the artifacts that were previously uploaded to be used here. This job will: -1. upload incompatible versions to gh-pages. These incompatible versions are named in the format `incompatible-forc-@fuel-core-`. +1. upload incompatible versions to `gh-pages`. These incompatible versions are named in the format `incompatible-forc-@fuel-core-`. -2. update the channel by filtering for the latest versions of `forc` and `fuel-core` that passed tests within the matrix by running `index-versions.sh`. These are named in the format `compatible-forc-@fuel-core-`. Note that these files are not saved or uploaded onto gh-pages - they are only a way for the `test-toolchain-compatibility` job to share test results with this job. +2. update the channel by filtering for the latest versions of `forc` and `fuel-core` that passed tests within the matrix by running `index-versions.sh`. These are named in the format `compatible-forc-@fuel-core-`. Note that these files are not saved or uploaded onto `gh-pages` - they are only a way for the `test-toolchain-compatibility` job to share test results with this job. ### Debugging the workflow @@ -79,7 +79,7 @@ Some changes you might want to make to allow for easier testing: 2. You can also exit with 0 or 1 in jobs or steps where you want it to pass/fail. -You may also use [nektos/act](https://github.com/nektos/act) to run the workflow(s) locally. +You may also use [`nektos/act`](https://github.com/nektos/act) to run the workflow(s) locally. [sway-nightly-binaries]: https://github.com/FuelLabs/sway-nightly-binaries/releases [latest]: #the-latest-channel diff --git a/docs/src/concepts/how_fuelup_works.md b/docs/src/concepts/how_fuelup_works.md index 335ff3cee..eddaaf67a 100644 --- a/docs/src/concepts/how_fuelup_works.md +++ b/docs/src/concepts/how_fuelup_works.md @@ -8,7 +8,7 @@ toolchains and presents them all through a single set of tools within `~/.fuelup Generally, it is not recommended to manually make changes to the fuelup directory, otherwise `fuelup` might not function as expected. If you have made changes to the directory, we recommend removing -the entire directory and re-installing fuelup with [fuelup-init]. +the entire directory and re-installing fuelup with [`fuelup-init`]. ## Proxies @@ -39,7 +39,7 @@ turn executes the correct version of `forc` based on either an override file (`f or your currently active toolchain (in order of priority). -[fuelup-init]: ../installation/index.md#quickstart +[`fuelup-init`]: ../installation/index.md#quickstart [`rustup`]: https://github.com/rust-lang/rustup [`forc`]: https://fuellabs.github.io/sway/master/book/forc/index.html [`fuel-core`]: https://github.com/FuelLabs/fuel-core diff --git a/docs/src/concepts/toolchains.md b/docs/src/concepts/toolchains.md index 8a4d5c707..d6f109163 100644 --- a/docs/src/concepts/toolchains.md +++ b/docs/src/concepts/toolchains.md @@ -5,7 +5,7 @@ Many `fuelup` commands deal with _toolchains_, a single installation of the Fuel toolchain. `fuelup` supports **two** types of toolchains. -1. Distributable toolchains which track the official release [channels] (eg, _latest_, _nightly_); +1. Distributable toolchains which track the official release [channels] (e.g., _latest_, _nightly_); 2. Custom toolchains and install individual components in a modular manner. @@ -36,7 +36,7 @@ For most use cases, using the officially packaged toolchains is good enough. For advanced use cases, `fuelup` allows you to build a toolchain in a modular manner, and to specify specific versions of components to install. -To init a new, empty toolchain: +To initialize a new, empty toolchain: ```sh fuelup toolchain new my_toolchain diff --git a/docs/src/configuration.md b/docs/src/configuration.md index 4175bbc58..4e96780b3 100644 --- a/docs/src/configuration.md +++ b/docs/src/configuration.md @@ -69,9 +69,9 @@ Now you can install the completions script using the following command: fuelup completions --shell=zsh > ~/.zfunc/_fuelup ``` -### POWERSHELL +### PowerShell -The powershell completion scripts require PowerShell v5.0+ (which comes with Windows 10, but can be +The `powershell` completion scripts require PowerShell v5.0+ (which comes with Windows 10, but can be downloaded separately for windows 7 or 8.1). First, check if a profile has already been set diff --git a/docs/src/developer_guide/adding_components.md b/docs/src/developer_guide/adding_components.md index 6ce0ffd8a..48f3b3bc2 100644 --- a/docs/src/developer_guide/adding_components.md +++ b/docs/src/developer_guide/adding_components.md @@ -3,7 +3,7 @@ Adding components in `fuelup` is often just a small PR to [`components.toml`] in the repo, followed by a new release of `fuelup`. -## Contributing to components.toml +## Contributing to `components.toml` This section describes how you may add support for a binary within `fuelup`. diff --git a/docs/src/developer_guide/building_a_channel.md b/docs/src/developer_guide/building_a_channel.md index d96c990e7..b0463b42a 100644 --- a/docs/src/developer_guide/building_a_channel.md +++ b/docs/src/developer_guide/building_a_channel.md @@ -19,16 +19,16 @@ This script's main usage is found within the `fuelup` CI. This script is in char The `latest` channel is re-built if the [check versions workflow] detects a new release of `forc` or `fuel-core`, and compatibility tests pass after that. This is explained in detail in the [latest channel developer guide]. -An example of this usage is in [test-toolchain-compatibility.yml]. +An example of this usage is in [`test-toolchain-compatibility.yml`]. The `nightly` channel is more straightforward - a channel is built at 01:00 UTC every day, containing the download links to binaries found within the [sway-nightly-binaries repository]. -An example of this usage is in [publish-nightly-channel.yml]. +An example of this usage is in [`publish-nightly-channel.yml`]. ### Manual -There may be times where we need a channel for a one-off event eg. testnets. During these events, we do not +There may be times where we need a channel for a one-off event e.g. testnets. During these events, we do not require a routine update, and can essentially publish once and be done. This is when manual publishing is done. For example, building a `beta-3` toolchain is done like so: @@ -38,7 +38,7 @@ For example, building a `beta-3` toolchain is done like so: cd ci/build-channel && cargo run -- channel-fuel-beta-3.toml 2023-02-13 forc=0.35.0 fuel-core=0.17.1 ``` -The above command means that we're building a channel named `channel-fuel-beta-3.toml` with the date `2023-02-13` (YYYY-MM-DD) +The above command means that we're building a channel named `channel-fuel-beta-3.toml` with the date `2023-02-13` (`YYYY-MM-DD`) and `forc` and `fuel-core` versions `0.35.0` and `0.17.1` respectively, and the latest versions for the other unlisted components. Other than for these one-off events, manually running `build-channel` locally is a good sanity check when working @@ -62,7 +62,7 @@ on this codebase. `PACKAGES` -- _Optional_. A list of key-value pairs mapping component names to [SemVer]-compatible versions, eg. 'fuel-core=0.17.1' +- _Optional_. A list of key-value pairs mapping component names to [SemVer]-compatible versions, e.g. 'fuel-core=0.17.1' ### Options @@ -73,9 +73,9 @@ on this codebase. [Usage]: #usage [check versions workflow]: https://github.com/FuelLabs/fuelup/actions/workflows/index-versions.yml [latest channel developer guide]: ../concepts/channels.md#understanding-the-latest-workflow -[test-toolchain-compatibility.yml]: https://github.com/FuelLabs/fuelup/blob/3abe817673184ac17a78b2a8965234813ac6d911/.github/workflows/test-toolchain-compatibility.yml#L174 +[`test-toolchain-compatibility.yml`]: https://github.com/FuelLabs/fuelup/blob/3abe817673184ac17a78b2a8965234813ac6d911/.github/workflows/test-toolchain-compatibility.yml#L174 [sway-nightly-binaries repository]: https://github.com/FuelLabs/sway-nightly-binaries -[publish-nightly-channel.yml]: https://github.com/FuelLabs/fuelup/blob/3abe817673184ac17a78b2a8965234813ac6d911/.github/workflows/publish-nightly-channel.yml#L37 +[`publish-nightly-channel.yml`]: https://github.com/FuelLabs/fuelup/blob/3abe817673184ac17a78b2a8965234813ac6d911/.github/workflows/publish-nightly-channel.yml#L37 [channel]: ../concepts/channels.md [variable]: https://docs.github.com/en/actions/learn-github-actions/variables [SemVer]: https://semver.org/ diff --git a/docs/src/index.md b/docs/src/index.md index 5373b192c..e3f646e61 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -12,8 +12,7 @@ Check out the [Concepts] chapter for an overview of how _fuelup_ works and some of the terminology it uses. The [Installation] chapter covers installing fuelup and getting started. -The source code of _fuelup_ and this manual may be found at -. If you find a problem, check out the +The source code of _fuelup_ and this manual may be found [here](https://github.com/FuelLabs/fuelup). If you find a problem, check out the [issue tracker]. Release notes for _fuelup_ may be found under [Releases] in our GitHub repository. diff --git a/docs/src/installation/other.md b/docs/src/installation/other.md index e0c671b2f..ac9c0ff04 100644 --- a/docs/src/installation/other.md +++ b/docs/src/installation/other.md @@ -10,8 +10,7 @@ use [Windows Subsystem for Linux]. ## Building from source -You can also install `fuelup` from source. Check out the git repository from - and run `cargo run --release`. +You can also install `fuelup` from source. Check out the [git repository](https://github.com/FuelLabs/fuelup) and run `cargo run --release`. You should then manually move the `fuelup` binary to `.fuelup/bin`. diff --git a/docs/src/overrides.md b/docs/src/overrides.md index 4f7528983..93f8fe2ee 100644 --- a/docs/src/overrides.md +++ b/docs/src/overrides.md @@ -10,10 +10,10 @@ You can override the installed default toolchain using a `fuel-toolchain.toml` f ## The toolchain file - + -The fuel-toolchain.toml file allows projects to "pin" to a specific set of fuel toolchain component versions. -This greatly improves the reproducibility of a project, as the fuel-toolchain.toml contains the set of known, +The `fuel-toolchain.toml` file allows projects to "pin" to a specific set of fuel toolchain component versions. +This greatly improves the reproducibility of a project, as the `fuel-toolchain.toml` contains the set of known, working versions for each tool used to build it. When this file is present, `fuelup` will override the default toolchain with the specified toolchain when executing binaries