fix: re-order statements and add on-line help (#900)

 - Makefile line order is important, so by convention variables are declared at the top, then specific rules, then generic rules, and finally pattern rules. Make itself is flexible about these high-level groups, but not following this order can yield subtle and hard to debug problems as lines are parsed and interpreted as they are being read.

 - In this Makefile, we also use some parsing magic to generate an on-line help automatically, but this requires to follow the pattern:
```
 target-name: target-dependencies*   ## one-line on line help
```
   You can declare groups with `##@ group-name`. This affects only the presentation of the on-line help, please check the Makefile to see how it is used.

Author: sambuc

Makefile

@@ -141,6 +141,43 @@ tests: test_setup main_tests schemathesis_tests collect_coverage  ## Run all tes
 pre_commit_checks:  ## Run pre-commit checks
 	poetry run pre-commit run --all-files
 
+##@ Helm/k8s
+
+.PHONY: k3d_cluster
+k3d_cluster:  ## Creates a k3d cluster for testing
+	./setup-k3d-cluster.sh --reset --deploy-shipwright
+
+.PHONY: install_amaltheas
+install_amaltheas:  ## Installs both version of amalthea in the. NOTE: It uses the currently active k8s context.
+	helm repo add renku https://swissdatasciencecenter.github.io/helm-charts
+	helm repo update
+	helm upgrade --install amalthea-js renku/amalthea --version $(AMALTHEA_JS_VERSION)
+	helm upgrade --install amalthea-se renku/amalthea-sessions --version ${AMALTHEA_SESSIONS_VERSION}
+
+# TODO: Add the version variables from the top of the file here when the charts are fully published
+.PHONY: amalthea_schema
+amalthea_schema:  ## Updates generates pydantic classes from CRDs
+	curl https://raw.githubusercontent.com/SwissDataScienceCenter/amalthea/${AMALTHEA_SESSIONS_VERSION}/config/crd/bases/amalthea.dev_amaltheasessions.yaml | yq '.spec.versions[0].schema.openAPIV3Schema' | poetry run datamodel-codegen --output components/renku_data_services/notebooks/cr_amalthea_session.py --base-class renku_data_services.notebooks.cr_base.BaseCRD ${CR_CODEGEN_PARAMS}
+	curl https://raw.githubusercontent.com/SwissDataScienceCenter/amalthea/${AMALTHEA_JS_VERSION}/controller/crds/jupyter_server.yaml | yq '.spec.versions[0].schema.openAPIV3Schema' | poetry run datamodel-codegen --output components/renku_data_services/notebooks/cr_jupyter_server.py --base-class renku_data_services.notebooks.cr_base.BaseCRD ${CR_CODEGEN_PARAMS}
+
+.PHONY: shipwright_schema
+shipwright_schema:  ## Updates the Shipwright pydantic classes
+	curl https://raw.githubusercontent.com/shipwright-io/build/refs/tags/v0.15.2/deploy/crds/shipwright.io_buildruns.yaml | yq '.spec.versions[] | select(.name == "v1beta1") | .schema.openAPIV3Schema' | poetry run datamodel-codegen --output components/renku_data_services/session/cr_shipwright_buildrun.py --base-class renku_data_services.session.cr_base.BaseCRD ${CR_CODEGEN_PARAMS}
+
+##@ Devcontainer
+
+.PHONY: devcontainer_up
+devcontainer_up:  ## Start dev containers
+	devcontainer up --workspace-folder .
+
+.PHONY: devcontainer_rebuild
+devcontainer_rebuild:  ## Rebuild dev containers images
+	devcontainer up --remove-existing-container --workspace-folder .
+
+.PHONY: devcontainer_exec
+devcontainer_exec: devcontainer_up ## Start a shell in the development container
+	devcontainer exec --container-id renku-data-services_devcontainer-data_service-1 -- bash
+
 ##@ General
 
 .PHONY: run
@@ -155,6 +192,13 @@ debug:  ## Debug the sanic server
 run-tasks:  ## Run the data tasks
 	DUMMY_STORES=true poetry run python bases/renku_data_services/data_tasks/main.py
 
+.PHONY: lock
+lock:  ## Update the lock files for all projects from their repsective poetry.toml
+	poetry lock $(ARGS)
+	poetry -C projects/renku_data_service lock $(ARGS)
+	poetry -C projects/secrets_storage lock $(ARGS)
+	poetry -C projects/k8s_watcher lock $(ARGS)
+	poetry -C projects/renku_data_tasks lock $(ARGS)
 
 # From the operator sdk Makefile
 # The help target prints out all targets with their descriptions organized
@@ -171,29 +215,6 @@ run-tasks:  ## Run the data tasks
 help:  ## Display this help.
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-25s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 
-##@ Helm/k8s
-
-.PHONY: k3d_cluster
-k3d_cluster:  ## Creates a k3d cluster for testing
-	./setup-k3d-cluster.sh --reset --deploy-shipwright
-
-.PHONY: install_amaltheas
-install_amaltheas:  ## Installs both version of amalthea in the. NOTE: It uses the currently active k8s context.
-	helm repo add renku https://swissdatasciencecenter.github.io/helm-charts
-	helm repo update
-	helm upgrade --install amalthea-js renku/amalthea --version $(AMALTHEA_JS_VERSION)
-	helm upgrade --install amalthea-se renku/amalthea-sessions --version ${AMALTHEA_SESSIONS_VERSION}
-
-# TODO: Add the version variables from the top of the file here when the charts are fully published
-.PHONY: amalthea_schema
-amalthea_schema:  ## Updates generates pydantic classes from CRDs
-	curl https://raw.githubusercontent.com/SwissDataScienceCenter/amalthea/${AMALTHEA_SESSIONS_VERSION}/config/crd/bases/amalthea.dev_amaltheasessions.yaml | yq '.spec.versions[0].schema.openAPIV3Schema' | poetry run datamodel-codegen --output components/renku_data_services/notebooks/cr_amalthea_session.py --base-class renku_data_services.notebooks.cr_base.BaseCRD ${CR_CODEGEN_PARAMS}
-	curl https://raw.githubusercontent.com/SwissDataScienceCenter/amalthea/${AMALTHEA_JS_VERSION}/controller/crds/jupyter_server.yaml | yq '.spec.versions[0].schema.openAPIV3Schema' | poetry run datamodel-codegen --output components/renku_data_services/notebooks/cr_jupyter_server.py --base-class renku_data_services.notebooks.cr_base.BaseCRD ${CR_CODEGEN_PARAMS}
-
-.PHONY: shipwright_schema
-shipwright_schema:  ## Updates the Shipwright pydantic classes
-	curl https://raw.githubusercontent.com/shipwright-io/build/refs/tags/v0.15.2/deploy/crds/shipwright.io_buildruns.yaml | yq '.spec.versions[] | select(.name == "v1beta1") | .schema.openAPIV3Schema' | poetry run datamodel-codegen --output components/renku_data_services/session/cr_shipwright_buildrun.py --base-class renku_data_services.session.cr_base.BaseCRD ${CR_CODEGEN_PARAMS}
-
 # Pattern rules
 
 API_SPEC_CODEGEN_PARAMS := ${CODEGEN_PARAMS}
@@ -205,25 +226,3 @@ API_SPEC_CODEGEN_PARAMS := ${CODEGEN_PARAMS}
 # newer than the requirements these steps won't be re-triggered.
 # Ignore the return value when there are more differences.
 	( git diff --exit-code -I "^#   timestamp\: " $@ >/dev/null && git checkout $@ ) || true
-
-# Devcontainer
-
-.PHONY: devcontainer_up
-devcontainer_up:
-	devcontainer up --workspace-folder .
-
-.PHONY: devcontainer_rebuild
-devcontainer_rebuild:
-	devcontainer up --remove-existing-container --workspace-folder .
-
-.PHONY: devcontainer_exec
-devcontainer_exec: devcontainer_up
-	devcontainer exec --container-id renku-data-services_devcontainer-data_service-1 -- bash
-
-.PHONY: lock
-lock:
-	poetry lock $(ARGS)
-	poetry -C projects/renku_data_service lock $(ARGS)
-	poetry -C projects/secrets_storage lock $(ARGS)
-	poetry -C projects/k8s_watcher lock $(ARGS)
-	poetry -C projects/renku_data_tasks lock $(ARGS)