ci: check docs spelling (#5527)

* Check docs spelling

* Add config

* Fix docs spelling

* Lint docs format

* docs(flamegraph): remove note about script that was removed

* sort wordlist

* Set sort algo

* Fix CI pipeline

* hope to fix CI ordering

* Disable wordlist sort check

* docs(CONTRIBUTING): remove merge conflict marker and add codeblock types

* refactor: change to pyspelling.yml for local runs

* docs: make spell-checking wordlist case insensitive

* fix: sort .wordlist.txt

* refactor: alphabetize script order

* fix: add docs/reference to gitignore

* docs: add codeblocks to pyspelling ignore and clear all errors

* docs: ignore possessive endings in spellcheck

* docs: clear spelling errors in package readmes

* docs: pyspelling fix generated cli.md

* feat(workflows): lint generated docs

* feat(workflows): add word sort to docs-check

* test: unsort wordlist

* fix: sort wordlist

* refactor(workflow): remove unused comments

---------

Co-authored-by: matthewkeil <me@matthewkeil.com>
Co-authored-by: Cayman <caymannava@gmail.com>

.github/workflows/docs-check.yml

@@ -0,0 +1,50 @@
+name: Check docs
+
+on:
+  push:
+    # We intentionally don't run push on feature branches. See PR for rational.
+    branches: [unstable, stable]
+  pull_request:
+
+jobs:
+  build:
+    name: Docs spellcheck
+    runs-on: ubuntu-latest
+    steps:
+      # <common-build> - Uses YAML anchors in the future
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - name: Node.js version
+        id: node
+        run: echo "v8CppApiVersion=$(node --print "process.versions.modules")" >> $GITHUB_OUTPUT
+      - name: Restore dependencies
+        uses: actions/cache@master
+        id: cache-deps
+        with:
+          path: |
+            node_modules
+            packages/*/node_modules
+          key: ${{ runner.os }}-${{ steps.node.outputs.v8CppApiVersion }}-${{ hashFiles('**/yarn.lock', '**/package.json') }}
+      - name: Install & build
+        if: steps.cache-deps.outputs.cache-hit != 'true'
+        run: yarn install --frozen-lockfile && yarn build
+      - name: Build
+        run: yarn build
+        if: steps.cache-deps.outputs.cache-hit == 'true'
+
+      - name: Check wordlist is sorted
+        run: scripts/wordlist_sort_check.sh
+
+      - name: Build and collect docs
+        run: yarn build:docs
+
+      # Run prettier check with fix after generating the docs. The CLI reference is formatted with prettier for
+      # deployed version so this will fail if not "fixable"
+      - name: Check docs format
+        run: yarn lint-docs:fix
+
+      # Run spellcheck AFTER building docs, in case the CLI reference has issues
+      - name: Spellcheck
+        uses: rojopolis/spellcheck-github-actions@0.32.0

.github/workflows/docs.yml

@@ -36,12 +36,17 @@ jobs:
       - name: Build and collect docs
         run: yarn build:docs
 
+      - name: Lint built docs
+        run: yarn lint-docs:fix
+
       - name: Set up Python
         uses: actions/setup-python@v1
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r docs/requirements.txt
+
       - name: Build docs
         run: mkdocs build --site-dir site -v --clean
 

.github/workflows/test.yml

@@ -67,13 +67,10 @@ jobs:
         run: scripts/assert_eslintrc_sorted.mjs
 
       - name: Check Types
-        run: yarn run check-types
-      # Test docs generation, even if not published
-      - name: Build docs
-        run: yarn build:docs
+        run: yarn check-types
 
       - name: README check
-        run: yarn run check-readme
+        run: yarn check-readme
 
       - name: Lint
         run: yarn lint

.gitignore

@@ -40,10 +40,10 @@ packages/api/oapi-schemas
 # Autogenerated docs
 packages/**/docs
 packages/**/typedocs
+docs/assets
 docs/packages
+docs/reference
 docs/contributing.md
-docs/assets
-docs/reference/cli.md
 /site
 
 # Testnet artifacts
@@ -70,5 +70,6 @@ packages/cli/.git-data.json
 
 # Build artifacts
 .last_build_unixsec
+dictionary.dic
 
 temp/

.prettierignore

@@ -1,3 +1,5 @@
 **/lib
 **/.nyc_output
-/packages/*/spec-tests
+/packages/*/spec-tests
+node_modules
+**/node_modules

.pyspelling.yml

@@ -0,0 +1,42 @@
+matrix:
+  - name: markdown
+    aspell:
+      lang: en
+      ignore-case: true
+    dictionary:
+      wordlists:
+        - .wordlist.txt
+    pipeline:
+      - pyspelling.filters.url:
+      - pyspelling.filters.markdown:
+          markdown_extensions:
+          - pymdownx.superfences:
+          - pymdownx.highlight:
+          - pymdownx.striphtml:
+          - pymdownx.magiclink:
+      - pyspelling.filters.url:
+      - pyspelling.filters.html:
+          comments: false
+          ignores:
+            - code
+            - pre
+      - pyspelling.filters.context:
+          context_visible_first: true
+          delimiters:
+          # Ignore possessive endings
+          - open: '(?<=\w)''s(?!\w)'
+            close: '\b'
+          # Ignore eth methods (e.g. eth_estimateGas)
+          - open: '(?:\s)eth_(?:\w*)'
+            close: '\s'
+          # Ignore flags in cli.md
+          - open: '--(?:\w*)'
+            close: '[^\w]'
+          # Ignore hex strings
+          - open: '0x[a-fA-F0-9]'
+            close: '[^a-fA-F0-9]'
+    sources:
+      - "docs/**/*.md"
+      - "CONTRIBUTING.md"
+      - "README.md"
+      - "packages/*/README.md"

.wordlist.txt

@@ -0,0 +1,130 @@
+APIs
+AssemblyScript
+BLS
+BeaconNode
+Besu
+CLA
+CLI
+CTRL
+Chai
+ChainSafe
+Customizations
+Discv
+DockerHub
+Dockerized
+EIP
+EIPs
+EL
+ENR
+ENRs
+ESLint
+ETH
+Erigon
+EthStaker
+Ethereum
+FX
+Flamegraph
+Flamegraphs
+Github
+Gossipsub
+Grafana
+HackMD
+IPv
+Infura
+JSON
+JWT
+LGPL
+LGPLv
+LTS
+Lerna
+MEV
+MacOS
+Monorepo
+NPM
+NVM
+Nethermind
+NodeJS
+NodeSource
+PR
+PRs
+Plaintext
+PoS
+Quickstart
+RPC
+SHA
+SSD
+SSZ
+Stakehouse
+TOC
+TTD
+TypeScript
+UI
+UTF
+VM
+Vitalik
+Wagyu
+api
+async
+beaconcha
+bootnode
+bootnodes
+chainConfig
+chainsafe
+cli
+cmd
+config
+configs
+const
+constantish
+cors
+cryptographic
+dApp
+dApps
+decrypt
+deserialization
+devnet
+devnets
+enum
+envs
+flamegraph
+flamegraphs
+goerli
+interop
+keypair
+keystore
+keystores
+lightclient
+linter
+lockfile
+mainnet
+mdns
+merkle
+merkleization
+monorepo
+namespace
+namespaced
+namespaces
+nodemodule
+overriden
+params
+plaintext
+prover
+req
+reqresp
+runtime
+sharding
+ssz
+stakers
+subnets
+tcp
+testnet
+testnets
+todo
+typesafe
+udp
+util
+utils
+validator
+validators
+wip
+yaml