feat(Makefile): Add self-documenting commands and re-organise (#543)

Author: louismagowan

Makefile

@@ -1,31 +1,50 @@
-.PHONY: init lint check_lint test uml html cleandocs doctest
+#################################################################################
+# GLOBALS                                                                       #
+#################################################################################
 
-init:
+PACKAGE_DIR = causalpy
+
+#################################################################################
+# COMMANDS                                                                      #
+#################################################################################
+
+.PHONY: init lint check_lint test uml html cleandocs doctest help
+
+init: ## Install the package in editable mode
 	python -m pip install -e . --no-deps
 
-lint:
+lint: ## Run ruff linter and formatter
 	ruff check --fix .
 	ruff format .
 
-check_lint:
+check_lint: ## Check code formatting and linting without making changes
 	ruff check .
 	ruff format --diff --check .
 	interrogate .
 
-doctest:
+doctest: ## Run doctests for the causalpy module
 	python -m pytest --doctest-modules --ignore=causalpy/tests/ causalpy/ --config-file=causalpy/tests/conftest.py
 
-test:
+test: ## Run all tests with pytest
 	python -m pytest
 
-uml:
+uml: ## Generate UML diagrams from code
 	pyreverse -o png causalpy --output-directory docs/source/_static --ignore tests
 
-# Docs build commands
-
-html:
+html: ## Build HTML documentation with Sphinx
 	sphinx-build -b html docs/source docs/_build
 
-cleandocs:
+cleandocs: ## Clean the documentation build directories
 	rm -rf docs/_build
 	rm -rf docs/source/api/generated
+
+
+#################################################################################
+# Self Documenting Commands                                                     #
+#################################################################################
+
+.DEFAULT_GOAL := help
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+	awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'