chore: rework the makefile

.envrc

@@ -1,2 +1,3 @@
+export VIRTUAL_ENV=venv
 layout python
-python -c 'import pyparsing' 2> /dev/null || pip install pyparsing==3.0.9 black isort mypy
+python -c 'import pyparsing' 2> /dev/null || pip install -r scripts/requirements.txt

.gitignore

@@ -41,6 +41,7 @@ luac.out
 
 .direnv/
 .testenv/
+venv/
 doc/tags
 scripts/nvim_doc_tools
 scripts/nvim-typecheck-action

Makefile

@@ -1,23 +1,42 @@
-.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
 
-# Update the snapshot files
+## update_snapshots: Update the test snapshot files
+.PHONY: update_snapshots
 update_snapshots:
 	./run_tests.sh --update
 
+## 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
 
@@ -27,5 +46,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

scripts/requirements.txt

@@ -0,0 +1,4 @@
+pyparsing==3.0.9
+black
+isort
+mypy