Update setup docs, annotate makefile

docs/installation.md

@@ -17,9 +17,9 @@ After logging into Gitpod or creating an account we recommend also installing th
 
 2. After Gitpod is finished preparing the environment, it will open the workspace. Close any unnecessary terminal windows. To open a new fresh terminal window press ```Ctrl + ` ```.
 
-3. In almost all cases, you will need to have a _virtual environment_ set up so that the necessary commands for Django and other libraries are available to you. You can enter a virtual environment by typing `source .venv/bin/activate` from the the project root (i.e. `/workspace/admin-portal/`). You can tell you're a virtual environment - because your prompt will change from `gitpod /workspace/admin-portal (BRANCH_NAME) $` to `(.venv) gitpod /workspace/admin-portal (BRANCH_NAME) $`. Want more? [Learn more about virtual environments for python](https://realpython.com/python-virtual-environments-a-primer/)
+3. In almost all cases, you will need to have a _virtual environment_ set up so that the necessary commands for Django and other libraries are available to you. You can enter a virtual environment by typing `source .venv/bin/activate` from the the project root (i.e. `/workspace/admin-portal/`). You can tell you're a virtual environment - because your prompt will change from `gitpod /workspace/admin-portal (BRANCH_NAME) $` to `(.venv) gitpod /workspace/admin-portal (BRANCH_NAME) $`. Want more? [Learn more about virtual environments for python](https://realpython.com/python-virtual-environments-a-primer/).
 
-4. There is a makefile set up to allow easy access to common tasks, like running a development server, spinning up tailwind for front end development, creating a superuser and so on. There is tab-completion set up for github - to see the options available, type `make` and hit tab. You should see output like below:
+4. There is a makefile set up, to allow easy access to common tasks like running a development server, spinning up tailwind for front end development, creating a superuser and so on. There is tab-completion set up in Gitpod - so to see the options available, type `make` and hit tab in a new terminal. You should see output like below:
 
 ```
 (.venv) gitpod /workspace/admin-portal (BRANCH_NAME) $ make 

makefile

@@ -1,72 +1,78 @@
 .PHONY: release venv
 
-# used for tagging our docker images
+# used for tagging our docker images.
 TAG ?= $(shell echo $$APP_RELEASE)-$(shell git log -n 1 --format=%h)
 
 # Create Python virtual environment if not yet created.
 venv:
 	test -d .venv || python -m venv .venv
 
-## Installing
+## Deploy a new release to production. This will not work in Gitpod, as it relies on staff SSH keys for deployment. 
 release:
 	dotenv -f env.prod run -- sentry-cli releases new -p admin-portal $(shell sentry-cli releases propose-version)
 	dotenv -f env.prod run -- sentry-cli releases set-commits --auto $(shell sentry-cli releases propose-version)
 	dotenv -f env.prod run -- ansible-playbook ansible/deploy.yml -i ansible/inventories/prod.yml
 	dotenv -f env.prod run -- sentry-cli releases finalize $(shell sentry-cli releases propose-version)
 
+# Create a super user for local development using the basic django `createsuperuser` command.
 dev.createsuperuser:
 	dotenv run -- python ./manage.py createsuperuser --username admin --email admin@admin.commits --noinput
 	dotenv run -- python ./manage.py set_fake_passwords
 
+# Run a django development server that reloads when codes is changed.
 dev.runserver:
 	dotenv run -- python manage.py runserver
 
-# start the tailwind watcher
+# Start the tailwind watcher - this will re-run tailwind to generate css as code is changed.
 dev.tailwind.start:
 	dotenv run -- python manage.py tailwind start
 
-# install the front end dependencies
+# Install the front end dependencies.
 dev.tailwind.install: 
 	dotenv run -- python manage.py tailwind install
 
+# Run the django tests on a loop with with pytest, and re-running them when code is changed.
 dev.test:
 	dotenv run -- pytest -s --create-db --looponfail --ds=greenweb.settings.testing
 
+# Run the django tests on a loop with pytest, but only ones marked with `only'.
 dev.test.only:
 	dotenv run -- pytest -s --create-db --looponfail -m only -v  --ds=greenweb.settings.testing
 
+# Set up the github repo for data analysis against the Green Web Platform database.
 data_analysis_repo:
 	if test -d data-analysis; \
 	then echo "data-analysis repo already checked out";  \
 	else git clone https://github.com/thegreenwebfoundation/data-analysis.git; \
 	fi
 
-# start a marimo notebook session
+# Start a Marimo notebook session.
 notebook.gitpod: data_analysis_repo
 	# set up our start notebook with django initialised ready for queries
 	dotenv run -- marimo edit data-analysis/starter-notebook.py
 
 
-# Run a basic test(with pytest) that creates a database using the testing settings
+# Run the django tests (with pytest), creating a test database using the `testing` settings.
 test:
 	dotenv run -- pytest -s --create-db --ds=greenweb.settings.testing
 
+# As above, but only the tests marked 'only'.
 test.only:
 	dotenv run -- pytest -s --create-db -m only -v  --ds=greenweb.settings.testing
 
-# Build the documentation using Sphinx
+# Build the documentation using Sphinx.
 docs:
 	dotenv run -- sphinx-build ./docs _build/
 
-# Build the documentation using Sphinx and keep updating it on every change
+# Build the documentation using Sphinx and keep updating it on every change.
 docs.watch:
 	dotenv run -- sphinx-autobuild ./docs _build/
 
-# make a docker image for publishing to our registry
+# Make a docker image for publishing to our registry.
 docker.build:
 	docker build -t $(APP_NAME)
 
-# Push the current 
+# Push the current tagged image to our registry.
 docker.release:	
 	docker tag $(APP_NAME) $(DOCKER_REGISTRY):$(TAG)
 	docker push $(DOCKER_REGISTRY)/$(APP_NAME):$(TAG)