docs: add documentation to Makefile (#3)

* docs: add documentation to Makefile

* docs: group commands in Makefile

* docs: add Makefile docs description

Makefile

@@ -1,39 +1,79 @@
-unit-tests:
+# To do stuff with make, you type `make` in a directory that has a file called
+# "Makefile".  You can also type `make -f <makefile>` to use a different filename.
+#
+# A Makefile is a collection of rules. Each rule is a recipe to do a specific
+# thing, sort of like a grunt task or an npm package.json script.
+#
+# A rule looks like this:
+#
+# <target>: <prerequisites...>
+# 	<commands>
+#
+# The "target" is required. The prerequisites are optional, and the commands
+# are also optional, but you have to have one or the other.
+#
+# Type `make` to show the available targets and a description of each.
+#
+.DEFAULT_GOAL := help
+.PHONY: help
+help:  ## Display this help
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+##@ Testing
+
+.PHONY: unit-tests
+unit-tests: ## run unit-tests with pytest
 	@pytest
 
-unit-tests-cov:
+.PHONY: unit-tests-cov
+unit-tests-cov: ## run unit-tests with pytest and show coverage (terminal + html)
 	@pytest --cov=src --cov-report term-missing --cov-report=html
 
-unit-tests-cov-fail:
+.PHONY: unit-tests-cov-fail
+unit-tests-cov-fail: ## run unit tests with pytest and show coverage (terminal + html) & fail if coverage too low & create files for CI
 	@pytest --cov=src --cov-report term-missing --cov-report=html --cov-fail-under=80 --junitxml=pytest.xml | tee pytest-coverage.txt
 
-clean-cov:
-	@rm -rf .coverage
-	@rm -rf htmlcov
-	@rm -rf pytest.xml
-	@rm -rf pytest-coverage.txt
+##@ Formatting
 
-format-black:
+.PHONY: format-black
+format-black: ## black (code formatter)
 	@black .
 
-format-isort:
+.PHONY: format-isort
+format-isort: ## isort (import formatter)
 	@isort .
 
-lint-black:
+.PHONY: format
+format: format-black format-isort ## run all formatters
+
+##@ Linting
+
+.PHONY: lint-black
+lint-black: ## black in linting mode
 	@black . --check
 
-lint-isort:
+.PHONY: lint-isort
+lint-isort: ## isort in linting mode
 	@isort . --check
 
-lint-flake8:
+.PHONY: lint-flake8
+lint-flake8: ## flake8 (linter)
 	@flake8 .
 
-lint-mypy:
+.PHONY: lint-mypy
+lint-mypy: ## mypy (static-type checker)
 	@mypy --config-file pyproject.toml .
 
-lint-mypy-report:
+.PHONY: lint-mypy-report
+lint-mypy-report: ## run mypy & create report
 	@mypy --config-file pyproject.toml . --html-report ./mypy_html
 
-format: format-black format-isort
+lint: lint-black lint-isort lint-flake8 lint-mypy ## run all linters
+
+##@ Clean-up
 
-lint: lint-black lint-isort lint-flake8 lint-mypy
+clean-cov: ## remove output files from pytest & coverage
+	@rm -rf .coverage
+	@rm -rf htmlcov
+	@rm -rf pytest.xml
+	@rm -rf pytest-coverage.txt