docs(general): Split readme into readme/setup, and revert makefile ch…

…anges

{{ cookiecutter.project_name }}/Makefile

@@ -10,78 +10,82 @@ VERSION_FILE:=VERSION
 COMPOSE_FILE=docker/docker-compose.yml
 TAG:=$(shell cat ${VERSION_FILE})
 
+# takes advantage of the makefile structure (command; ## documentation)
+# to generate help
 help:
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
 git-tag:  ## Tag in git, then push tag up to origin
 	git tag $(TAG)
 	git push origin $(TAG)
 
-## Test lint compliance using black. Config in pyproject.toml file
-ci-black: dev-start
+
+ci-black: dev-start ## Test lint compliance using black. Config in pyproject.toml file
 	docker exec -t $(CONTAINER_NAME) black --check $(PROJ_DIR)
 
-## Test lint compliance using flake8. Config in tox.ini file
-ci-flake8: dev-start
+
+ci-flake8: dev-start ## Test lint compliance using flake8. Config in tox.ini file
 	docker exec -t $(CONTAINER_NAME) flake8 $(PROJ_DIR)
 
-## Runs unit tests using pytest
-ci-test: dev-start
+
+ci-test: dev-start ## Runs unit tests using pytest
 	docker exec -t $(CONTAINER_NAME) pytest $(PROJ_DIR)
 
-## Runs unit tests, with an interactive IPDB session at the first failure
-ci-test-interactive: dev-start
+
+ci-test-interactive: dev-start ## Runs unit tests with interactive IPDB session at the first failure
 	docker exec -it $(CONTAINER_NAME) pytest $(PROJ_DIR)  -x --pdb --pdbcls=IPython.terminal.debugger:Pdb
 
-## Runs mypy type checker
-ci-mypy: dev-start
+
+ci-mypy: dev-start ## Runs mypy type checker
 	docker exec -t $(CONTAINER_NAME) mypy --ignore-missing-imports --show-error-codes $(PROJ_DIR)
 
-## Check black, flake8, and run unit tests
-ci: ci-black ci-flake8 ci-test ci-mypy
+
+ci: ci-black ci-flake8 ci-test ci-mypy ## Check black, flake8, and run unit tests
 	@echo "CI successful"
 
-## Runs isort to sorts imports
-isort: dev-start
+
+isort: dev-start ## Runs isort to sorts imports
 	docker exec -t $(CONTAINER_NAME) isort -rc $(PROJ_DIR)  --profile black
 
-## Runs black auto-linter
-black: dev-start
+
+black: dev-start ## Runs black auto-linter
 	docker exec -t $(CONTAINER_NAME) black $(PROJ_DIR)
 
-## Formats repo; runs black and isort on all files
-format: isort black
+
+format: isort black ## Formats repo by running black and isort on all files
 	@echo "Formatting complete"
 
-## Deprecated. Here to support old workflow
-lint: format
 
-## Primary make command for devs, spins up containers
-dev-start:
+lint: format ## Deprecated. Here to support old workflow
+
+
+dev-start: ## Primary make command for devs, spins up containers
 	docker-compose -f $(COMPOSE_FILE) --project-name $(PROJECT) up -d --no-recreate
 
-## Spin down active containers
-dev-stop:
+
+dev-stop: ## Spin down active containers
 	docker-compose -f $(COMPOSE_FILE) --project-name $(PROJECT) down
 
-## Rebuild images for dev containers (useful when Dockerfile/requirements are updated)
-dev-rebuild:
+
+# Useful when Dockerfile/requirements are updated)
+dev-rebuild: ## Rebuild images for dev containers
 	docker-compose -f $(COMPOSE_FILE) --project-name $(PROJECT) up -d --build
 
-## Exec into docker bash terminal
-bash: dev-start
+
+bash: dev-start ## Provides an interactive bash shell in the container
 	docker exec -it $(CONTAINER_NAME) bash
 
-## Build docs using Sphinx and copy to docs folder (this makes it easy to publish to gh-pages)
-docs:
+
+# makes it easy to publish to gh-pages
+docs: ## Build docs using Sphinx and copy to docs folder
 	docker exec -e GRANT_SUDO=yes $(CONTAINER_NAME) bash -c "cd docsrc; make html"
 	@cp -a docsrc/_build/html/. docs
 
-## Provides an interactive ipython prompt
-ipython:
+
+ipython: ## Provides an interactive ipython prompt
 	docker exec -it $(CONTAINER_NAME) ipython
 
-## Clean out temp/compiled python files
-clean:
+
+clean: ## Clean out temp/compiled python files
 	find . -name __pycache__ -delete
 	find . -name "*.pyc" -delete