Merge pull request #17 from MITLibraries/update-readme-and-makefile

Update README and Makefile

Makefile

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

README.md

@@ -2,7 +2,7 @@
 
 A template repository for creating Python CLI applications.
 
-## App setup (delete this section and above after initial application setup)
+## App Setup (delete this section and above after initial application setup)
 
 1. Rename "my_app" to the desired app name across the repo. (May be helpful to do a project-wide find-and-replace).
 2. Update Python version if needed.
@@ -33,25 +33,21 @@ Description of the app
 - To lint the repo: `make lint`
 - To run the app: `pipenv run my_app --help`
 
-## Environment variables
+## Environment Variables
 
 ### Required
 
-```
-# If set to a valid Sentry DSN, enables Sentry exception monitoring. This is not needed for local development.
-SENTRY_DSN=
-
-# Set to `dev` for local development, this will be set to `stage` and `prod` in those environments by Terraform.
-WORKSPACE=
+```shell
+SENTRY_DSN=### If set to a valid Sentry DSN, enables Sentry exception monitoring. This is not needed for local development.
+WORKSPACE=### Set to `dev` for local development, this will be set to `stage` and `prod` in those environments by Terraform.
 ```
 
 ### Optional
 
 _Delete this section if it isn't applicable to the PR._
 
-```
-# Description for optional environment variable
-<OPTIONAL_ENV>=
+```shell
+<OPTIONAL_ENV>=### Description for optional environment variable
 ```