diff --git a/.envrc b/.envrc
index 175de894..32465e7a 100644
--- a/.envrc
+++ b/.envrc
@@ -1 +1,2 @@
+export VIRTUAL_ENV=venv
 layout python
diff --git a/.gitignore b/.gitignore
index 290f6569..c90db5d4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,6 +44,7 @@ __pycache__
 
 .direnv/
 .testenv/
+venv/
 doc/tags
 scripts/nvim_doc_tools
 scripts/nvim-typecheck-action
diff --git a/Makefile b/Makefile
index 71447f8f..47993682 100644
--- a/Makefile
+++ b/Makefile
@@ -1,19 +1,37 @@
-.PHONY: all doc test lint fastlint clean
-
+## help: print this help message
+.PHONY: help
+help:
+	@echo 'Usage:'
+	@sed -n 's/^##//p' ${MAKEFILE_LIST} | column -t -s ':' |  sed -e 's/^/ /'
+
+## all: generate docs, lint, and run tests
+.PHONY: all
 all: doc lint test
 
-doc: scripts/nvim_doc_tools
-	python scripts/main.py generate
-	python scripts/main.py lint
+venv:
+	python3 -m venv venv
+	venv/bin/pip install -r scripts/requirements.txt
+
+## doc: generate documentation
+.PHONY: doc
+doc: scripts/nvim_doc_tools venv
+	venv/bin/python scripts/main.py generate
+	venv/bin/python scripts/main.py lint
 
+## test: run tests
+.PHONY: test
 test:
 	./run_tests.sh
 
+## lint: run linters and LuaLS typechecking
+.PHONY: lint
 lint: scripts/nvim-typecheck-action fastlint
 	./scripts/nvim-typecheck-action/typecheck.sh --workdir scripts/nvim-typecheck-action lua
 
-fastlint: scripts/nvim_doc_tools
-	python scripts/main.py lint
+## fastlint: run only fast linters
+.PHONY: fastlint
+fastlint: scripts/nvim_doc_tools venv
+	venv/bin/python scripts/main.py lint
 	luacheck lua tests --formatter plain
 	stylua --check lua tests
 
@@ -23,5 +41,7 @@ scripts/nvim_doc_tools:
 scripts/nvim-typecheck-action:
 	git clone https://github.com/stevearc/nvim-typecheck-action scripts/nvim-typecheck-action
 
+## clean: reset the repository to a clean state
+.PHONY: clean
 clean:
-	rm -rf scripts/nvim_doc_tools scripts/nvim-typecheck-action
+	rm -rf scripts/nvim_doc_tools scripts/nvim-typecheck-action venv .testenv
diff --git a/scripts/requirements.txt b/scripts/requirements.txt
new file mode 100644
index 00000000..2c6271fd
--- /dev/null
+++ b/scripts/requirements.txt
@@ -0,0 +1,4 @@
+pyparsing==3.0.9
+black
+isort
+mypy