Add help command to Makefile

Why these changes are being introduced:
* Provide simple documentation for Makefile commands

How this addresses that need:
* Add template for documenting commands using comments

Side effects of this change:
* I adjusted the comment slightly to pull comments marked by a single hash (#)
as opposed to two. To document a Makefile command, the description must be a comment
that appears next to the command declaration, denoted by a single hash.

Relevant ticket(s):
* https://mitlibraries.atlassian.net/browse/IN-894

Author: jonavellecuerdo

Makefile

@@ -1,13 +1,17 @@
 SHELL=/bin/bash
 DATETIME:=$(shell date -u +%Y%m%dT%H%M%SZ)
 
+help: # preview Makefile commands
+	@awk 'BEGIN { FS = ":.*#"; print "Usage:  make <target>\n\nTargets:" } \
+/^[-_[:alpha:]]+:.?*#/ { printf "  %-15s%s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
 ## ---- Dependency commands ---- ##
 
-install: # install dependencies
+install: # install Python dependencies
 	pipenv install --dev
 	pipenv run pre-commit install
 
-update: install # update all Python dependencies
+update: install # update Python dependencies
 	pipenv clean
 	pipenv update --dev
 
@@ -17,33 +21,32 @@ test: # run tests and print a coverage report
 	pipenv run coverage run --source=my_app -m pytest -vv
 	pipenv run coverage report -m
 
-coveralls: test
+coveralls: test # write coverage data to an LCOV report
 	pipenv run coverage lcov -o ./coverage/lcov.info
 
 
 ## ---- Code quality and safety commands ---- ##
 
-# linting commands
-lint: black mypy ruff safety 
+lint: black mypy ruff safety # run linters
 
-black:
+black: # run 'black' linter and print a preview of suggested changes
 	pipenv run black --check --diff .
 
-mypy:
+mypy: # run 'mypy' linter
 	pipenv run mypy .
 
-ruff:
+ruff: # run 'ruff' linter and print a preview of errors
 	pipenv run ruff check .
 
-safety:
+safety: # check for security vulnerabilities and verify Pipfile.lock is up-to-date
 	pipenv check
 	pipenv verify
 
-# apply changes to resolve any linting errors
-lint-apply: black-apply ruff-apply
+lint-apply: # apply changes with 'black' and resolve 'fixable errors' with 'ruff'
+	black-apply ruff-apply 
 
-black-apply: 
+black-apply: # apply changes with 'black'
 	pipenv run black .
 
-ruff-apply: 
+ruff-apply: # resolve 'fixable errors' with 'ruff'
 	pipenv run ruff check --fix .

README.md

@@ -26,6 +26,7 @@ Description of the app
 
 ## Development
 
+- To preview a list of available Makefile commands: `make help`
 - To install with dev dependencies: `make install`
 - To update dependencies: `make update`
 - To run unit tests: `make test`