docs: add markdown linting and spellcheck

.github/workflows/test.yaml

@@ -39,7 +39,15 @@ jobs:
           wget -O $GITHUB_WORKSPACE/bin/solc https://binaries.soliditylang.org/linux-amd64/$RELEASE_NAME
           chmod a+x $GITHUB_WORKSPACE/bin/solc
           echo $GITHUB_WORKSPACE/bin >> $GITHUB_PATH
+      - name: Install Aspell
+        run: |
+          sudo apt-get install aspell aspell-en
       - name: Install Tox and any other packages
-        run: pip install tox requests
+        run: pip install tox
       - name: Run Tox (CPython)
         run: tox
+      - uses: DavidAnson/markdownlint-cli2-action@v11
+        with:
+          globs: |
+            README.md
+            docs/**/*.md

.gitignore

@@ -58,4 +58,6 @@ verify_kzg_proof
 .cache
 _readthedocs
 site
-venv-docs/
+venv-docs/
+.pyspelling_en.dict
+whitelist.txt

.markdownlint.yaml

@@ -0,0 +1,5 @@
+# All rules: https://github.com/DavidAnson/markdownlint#rules--aliases
+default: true  # Default state for all rules
+MD013: false  # line-length: We don't fill paragaraphs/limit line length
+MD034: false  # no-bare-urls - We use pymdownx.magiclink which allows bare urls
+MD046: false  # code-block-style - This doesn't play well with material's admonitions)

.pyspelling.yml

@@ -0,0 +1,24 @@
+matrix:
+- name: markdown
+  pipeline:
+  - pyspelling.filters.markdown:
+  - pyspelling.filters.html:
+      comments: false
+      attributes:
+      - title
+      - alt
+      ignores:
+      - code
+      - pre
+      - a
+  aspell:
+    lang: en
+    d: en_US
+  dictionary:
+    wordlists:
+      - .wordlist.txt
+      - .wordlist_opcodes.txt
+      - .wordlist_python_pytest.txt
+    output: .pyspelling_en.dict
+  sources:
+  - 'docs/**/*.md'

.vscode/extensions.json

@@ -8,9 +8,13 @@
 		"ms-python.flake8",
 		"ms-python.black-formatter",
 		"esbenp.prettier-vscode",
+		"njpwerner.autodocstring",  // https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring
 		"streetsidesoftware.code-spell-checker",
 		"tamasfe.even-better-toml",
+		"bierner.markdown-mermaid",  // https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid
+		"bpruitt-goddard.mermaid-markdown-syntax-highlighting",  // https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting
+		"DavidAnson.vscode-markdownlint",  // https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
 	],
 	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
 	"unwantedRecommendations": []
-}
+}

.vscode/settings.recommended.json

@@ -6,6 +6,18 @@
             "description": "Words used in this project",
             "addWords": true
         },
+        "opcodes": {
+            "name": "opcodes",
+            "path": "${workspaceRoot}/.wordlist_opcodes.txt",
+            "description": "List of EVM opcodes",
+            "addWords": true
+        },
+        "python_pytest": {
+            "name": "python_pytest",
+            "path": "${workspaceRoot}/.wordlist_python_pytest.txt",
+            "description": "List of python and pytest related words",
+            "addWords": true
+        },
         "custom": true, // Enable the `custom` dictionary
         "internal-terms": false // Disable the `internal-terms` dictionary
     },
@@ -17,6 +29,7 @@
             "source.organizeImports": true
         }
     },
+    "python.analysis.autoFormatStrings": true,
     "python.linting.mypyEnabled": true,
     "python.linting.flake8Enabled": true,
     "python.testing.promptToConfigure": false,

.wordlist.txt

@@ -0,0 +1,270 @@
+addr
+address2
+alloc
+base64
+big0
+big1
+blockchain
+bls
+bytecode
+bytes8
+bytes20
+bytes32
+calc
+cli2
+coinbase
+coincurve
+crypto
+dao
+dup
+eip
+eips
+eth
+ethash
+ethereum
+evm
+evmone
+fn
+forkchoice
+geth
+hash32
+instantiation
+hasher
+ispkg
+keccak
+keccak256
+key2
+kzg
+kzgs
+listdir
+ommer
+ommers
+parseable
+pathlib
+petersburg
+precompile
+randao
+rlp
+secp256k1
+sharding
+cancun
+t8n
+trie
+txs
+wd
+wds
+u256
+utils
+util
+validator
+vm
+gwei
+wei
+islice
+0xaa
+
+getmtime
+byteorder
+delitem
+dirname
+endianness
+fromhex
+getitem
+metaclass
+radd
+setitem
+splitext
+textwrap
+zfill
+
+lll
+lllc
+solc
+yul
+
+address
+at5
+balance
+origin
+caller
+callvalue
+calldata
+calldataload
+calldatasize
+calldatacopy
+codesize
+codecopy
+gasprice
+extcodesize
+extcodecopy
+initcode
+returndatasize
+returndatacopy
+extcodehash
+blockhash
+coinbase
+timestamp
+time15k
+number
+difficulty
+gaslimit
+chainid
+selfbalance
+basefee
+ommer
+prevrandao
+
+docstrings
+hexsha
+mkdocs
+mkdocstrings
+nav
+repo
+
+evaluatable
+
+GHSA
+danceratopz
+Pomerantz
+
+acl
+api
+bb
+BlockchainTest
+BlockchainTestFiller
+blocknum
+blueswen
+br
+cd
+codeAddr
+compilable
+config
+contractAddr
+controlflow
+cp
+customizations
+Customizations
+danceratopz
+datastructures
+dev
+dir
+discordapp
+EIPs
+env
+eof
+esbenp
+executables
+fname
+formatOnSave
+formatter
+func
+GeneralStateTestsFiller
+gh
+github
+Github
+git's
+glightbox
+homebrew
+html
+https
+ignoreRevsFile
+img
+incrementing
+init
+io
+isort
+isort's
+itemName
+jimporter
+jq
+json
+JSON
+len
+linux
+london
+macos
+mainnet
+marioevz
+markdownlint
+md
+Misspelled words:
+mypy
+namespace
+ncheck
+nexternal
+nGo
+nJSON
+nop
+NOP
+NOPs
+nPython
+nSHA
+opc
+oprypin
+pdb
+png
+ppa
+ppas
+pre
+Pre
+prepend
+programmatically
+px
+py
+pyspelling
+pytest
+Pytest
+pytestArgs
+pytest's
+qGpsxSA
+quickstart
+readthedocs
+repo's
+repos
+runtime
+sandboxed
+sha
+SHA
+soliditylang
+spencertaylorbrown
+spencertb
+squidfunk
+src
+stackoverflow
+StateTest
+StateTestFiller
+stExample
+str
+streetsidesoftware
+subdirectories
+subdirectory
+subgraph
+substring
+sudo
+tamasfe
+TestAddress
+TestMultipleWithdrawalsSameAddress
+toml
+tox
+Tox
+tx
+txt
+ty
+typehints
+ubuntu
+ukiyo
+uncomment
+venv
+visualstudio
+vscode
+vv
+wikipedia
+wordlist
+www
+xF
+xFA
+xFD
+xFF
+yaml
+YAML
+yml