Refactor: Improve make help output (nhs-england-tools#118)

## Description

- Improve `make help` output.
- Fix issue with `Dockerfile` processing when replacing image from
latest placeholder
- Ensure `make` command line arguments are distinctive for the `docker`
and `terraform` modules

## Context

### Current output (v2)

<img width="1024" alt="image"
src="https://github.com/nhs-england-tools/repository-template/assets/499338/e8e6800f-9510-45ae-bb70-4d044adb4752">

### Previous output (v1)

<img width="1024" alt="image"
src="https://github.com/nhs-england-tools/repository-template/assets/499338/f577aa1f-a261-4a51-ae20-25f5093f5f85">

### Legacy output

<img width="2050" alt="image"
src="https://github.com/nhs-england-tools/repository-template/assets/499338/60a2b2fd-1f19-4e9f-883a-5b5903f85d3d">

### Testing

```
# clone the repo and switch to the `Improve_make_help_output` branch, then run:
$ make help
```

## Type of changes

- [x] Refactoring (non-breaking change)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would change existing
functionality)
- [x] Bug fix (non-breaking change which fixes an issue)

## Checklist

- [x] I am familiar with the [contributing
guidelines](../docs/CONTRIBUTING.md)
- [x] I have followed the code style of the project
- [x] I have added tests to cover my changes
- [x] I have updated the documentation accordingly
- [ ] This PR is a result of pair or mob programming

---

## Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others
privacy, we kindly ask you to NOT including [PII (Personal Identifiable
Information) / PID (Personal Identifiable
Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public)
or any other sensitive data in this PR (Pull Request) and the codebase
changes. We will remove any PR that do contain any sensitive
information. We really appreciate your cooperation in this matter.

- [x] I confirm that neither PII/PID nor sensitive data are included in
this PR and the codebase changes.

Author: stefaniuk

Makefile

@@ -7,23 +7,23 @@ include scripts/init.mk
 
 # Example CI/CD targets are: dependencies, build, publish, deploy, clean, etc.
 
-dependencies: # Install dependencies needed to build and test the project
+dependencies: # Install dependencies needed to build and test the project @Pipeline
 	# TODO: Implement installation of your project dependencies
 
-build: # Build the project artefact
+build: # Build the project artefact @Pipeline
 	# TODO: Implement the artefact build step
 
-publish: # Publish the project artefact
+publish: # Publish the project artefact @Pipeline
 	# TODO: Implement the artefact publishing step
 
-deploy: # Deploy the project artefact to the target environment
+deploy: # Deploy the project artefact to the target environment @Pipeline
 	# TODO: Implement the artefact deployment step
 
-clean:: # Clean-up project resources
+clean:: # Clean-up project resources (main) @Operations
 	# TODO: Implement project resources clean-up step
 
-config:: # Configure development environment
-	# TODO: Use only `make` targets that are specific to this project, e.g. you may not need to install Node.js
+config:: # Configure development environment (main) @Configuration
+	# TODO: Use only 'make' targets that are specific to this project, e.g. you may not need to install Node.js
 	make \
 		nodejs-install \
 		python-install \

docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md

@@ -126,7 +126,7 @@ As a result of the above decision
 - the name of the file will be `check-file-format.sh`
 - there will be a `pre-commit` runner installed by the [pre-commit](https://pre-commit.com/) framework using a make target
 - the GitHub Action will call the git hook `check-file-format.sh` script directly
-- and a couple of `Makefile` targets like `config`, `githooks-install` will be implemented to bootstrap the project
+- and a couple of `Makefile` targets like `config`, `githooks-config` will be implemented to bootstrap the project
 
 The intention of this decision is to guide any other git hook and GitHub Action implementations.
 

docs/developer-guides/Bash_and_Make.md

@@ -7,17 +7,23 @@
   - [Conventions](#conventions)
     - [Debugging](#debugging)
     - [Scripts](#scripts)
-  - [TODO](#todo)
 
 ## Using Make
 
-Sample make target definition:
+Sample make target signature definition:
 
 ```makefile
-some-target: # Short target description - mandatory: foo=[description]; optional: baz=[description, default is 'qux']
+some-target: # Target description - mandatory: foo=[description]; optional: baz=[description, default is 'qux'] @Category
     # Recipe implementation...
 ```
 
+- `some-target`: This is the name of the target you would specify when you want to run this particular target. Use the kebab-case naming convention and prefix with an underscore `_` to mark it as a "private" target. The first part of the name is used for grouping, e.g. `docker-*` or `terraform-*`.
+- `Target Description`: Provided directly after the target name as a single line, so be concise.
+- `mandatory` parameters: Parameters that must be provided when invoking the target. Each parameter has its own description. Please, follow the specified format as it is used by `make help`.
+- `optional` parameters: Parameters that are not required when invoking the target. They may have a default value. Each parameter has its own description.
+- `@Category` label: Used for grouping by the `make help` command.
+- `Recipe implementation`: This section defines the actual commands or steps the target will execute. **Do not exceed 5 lines of effective code**. For more complex operations, use a shell script. Refer to the `docker-build` implementation in the [docker.mk](../../scripts/docker/docker.mk) file. More complex operations are implemented in the [docker.sh](../../scripts/docker/docker.lib.sh) script for readability and simplicity.
+
 Run make target from a terminal:
 
 ```shell
@@ -31,6 +37,10 @@ All make targets should be added to the `${VERBOSE}.SILENT:` section of the `mak
 
 It is worth noting that by default, `make` creates a new system process to execute each line of a recipe. This is not the desired behaviour for us and the entire content of a make recipe (a target) should be run in a single shell invocation. This has been configured in this repository by setting the [`.ONESHELL:`](https://www.gnu.org/software/make/manual/html_node/One-Shell.html) special target in the `scripts/init.mk` file.
 
+To see all available make targets, run `make help`.
+
+![make help](./assets/make_help.png)
+
 ## Using Bash
 
 When working in the command-line ensure the environment variables are reset to their initial state. This can be done by reloading shell using the `env -i $SHELL` command.
@@ -141,10 +151,3 @@ You can combine it with the `VERBOSE` flag to see the details of the execution f
 ```shell
 VERBOSE=1 FORCE_USE_DOCKER=1 scripts/shellscript-linter.sh
 ```
-
-## TODO
-
-- Use of CLI tools installed and available on `$PATH`
-- Commands run in Docker containers when a CLI tool is not installed
-- Explain the concept of modules in this repository
-- Make is used as an orchestrator and tool to integrate development processes with the CI/CD pipeline

docs/developer-guides/assets/make_help.png

@@ -28,6 +28,6 @@ The [pre-commit](https://pre-commit.com/) framework is a powerful tool for manag
 You can run and test the process by executing the following commands from your terminal. These commands should be run from the top-level directory of the repository:
 
 ```shell
-make githooks-install
+make githooks-config
 make githooks-run
 ```

docs/user-guides/Run_Git_hooks_on_commit.md

@@ -24,8 +24,12 @@ function docker-build() {
 
   local dir=${dir:-$PWD}
 
-  _create-effective-dockerfile
   version-create-effective-file
+  _create-effective-dockerfile
+  # The current directory must be changed for the image build script to access
+  # assets that need to be copied
+  current_dir=$(pwd)
+  cd "$dir"
   docker build \
     --progress=plain \
     --platform linux/amd64 \
@@ -42,6 +46,7 @@ function docker-build() {
     --rm \
     --file "${dir}/Dockerfile.effective" \
     .
+  cd "$current_dir"
   # Tag the image with all the stated versions, see the documentation for more details
   for version in $(_get-all-effective-versions) latest; do
     docker tag "${DOCKER_IMAGE}:$(_get-effective-version)" "${DOCKER_IMAGE}:${version}"
@@ -217,14 +222,14 @@ function _replace-image-latest-by-specific-version() {
   local build_datetime=${BUILD_DATETIME:-$(date -u +'%Y-%m-%dT%H:%M:%S%z')}
 
   if [ -f "$versions_file" ]; then
-    # First, list the entries specific for Docker to take precedence, then the rest
-    content=$(grep " docker/" "$versions_file"; grep -v " docker/" "$versions_file")
+    # First, list the entries specific for Docker to take precedence, then the rest but exclude comments
+    content=$(grep " docker/" "$versions_file"; grep -v " docker/" "$versions_file" | grep -v "^#")
     echo "$content" | while IFS= read -r line; do
       [ -z "$line" ] && continue
       line=$(echo "$line" | sed "s/^#\s*//; s/\s*#.*$//" | sed "s;docker/;;")
       name=$(echo "$line" | awk '{print $1}')
       version=$(echo "$line" | awk '{print $2}')
-      sed -i "s;\(FROM .*\) ${name}:latest;\1 ${name}:${version};g" "$dockerfile"
+      sed -i "s;\(FROM .*\)${name}:latest;\1${name}:${version};g" "$dockerfile"
     done
   fi
 

scripts/docker/docker.lib.sh

@@ -4,48 +4,54 @@
 # Custom implementation - implementation of a make target should not exceed 5 lines of effective code.
 # In most cases there should be no need to modify the existing make targets.
 
-docker-build: # Build Docker image - optional: dir=[path to the Dockerfile to use, default is '.']
-	make _docker cmd="build"
+docker-build: # Build Docker image - optional: docker_dir|dir=[path to the Dockerfile to use, default is '.'] @Development
+	make _docker cmd="build" \
+		dir=$(or ${docker_dir}, ${dir})
+	file=$(or ${docker_dir}, ${dir})/Dockerfile.effective
+	scripts/docker/dockerfile-linter.sh
 
-docker-push: # Push Docker image - optional: dir=[path to the image directory where the Dockerfile is located, default is '.']
-	make _docker cmd="push"
+docker-push: # Push Docker image - optional: docker_dir|dir=[path to the image directory where the Dockerfile is located, default is '.'] @Development
+	make _docker cmd="push" \
+		dir=$(or ${docker_dir}, ${dir})
 
-clean:: # Remove Docker resources - optional: dir=[path to the image directory where the Dockerfile is located, default is '.']
-	make _docker cmd="clean"
+clean:: # Remove Docker resources (docker) - optional: docker_dir|dir=[path to the image directory where the Dockerfile is located, default is '.'] @Operations
+	make _docker cmd="clean" \
+		dir=$(or ${docker_dir}, ${dir})
 
-_docker: # Docker command wrapper - mandatory: cmd=[command to execute]
+_docker: # Docker command wrapper - mandatory: cmd=[command to execute]; optional: dir=[path to the image directory where the Dockerfile is located, relative to the project's top-level directory, default is '.']
 	# 'DOCKER_IMAGE' and 'DOCKER_TITLE' are passed to the functions as environment variables
 	DOCKER_IMAGE=$(or ${DOCKER_IMAGE}, $(or ${docker_image}, $(or ${IMAGE}, $(or ${image}, ghcr.io/org/repo))))
 	DOCKER_TITLE=$(or "${DOCKER_TITLE}", $(or "${docker_title}", $(or "${TITLE}", $(or "${title}", "Service Docker image"))))
 	source scripts/docker/docker.lib.sh
-	docker-${cmd} # 'dir' is passed to the function as environment variables, if set
+	dir=$(realpath ${dir})
+	docker-${cmd} # 'dir' is accessible by the function as environment variable
 
 # ==============================================================================
 # Quality checks - please, DO NOT edit this section!
 
-docker-shellscript-lint: # Lint all Docker module shell scripts
+docker-shellscript-lint: # Lint all Docker module shell scripts @Quality
 	for file in $$(find scripts/docker -type f -name "*.sh"); do
 		file=$${file} scripts/shellscript-linter.sh
 	done
 
 # ==============================================================================
 # Module tests and examples - please, DO NOT edit this section!
 
-docker-test-suite-run: # Run Docker test suite
+docker-test-suite-run: # Run Docker test suite @ExamplesAndTests
 	scripts/docker/tests/docker.test.sh
 
-docker-example-build: # Build Docker example
+docker-example-build: # Build Docker example @ExamplesAndTests
 	source scripts/docker/docker.lib.sh
 	cd scripts/docker/examples/python
 	DOCKER_IMAGE=repository-template/docker-example-python
 	DOCKER_TITLE="Repository Template Docker Python Example"
 	docker-build
 
-docker-example-lint: # Lint Docker example
+docker-example-lint: # Lint Docker example @ExamplesAndTests
 	dockerfile=scripts/docker/examples/python/Dockerfile
 	file=$${dockerfile} scripts/docker/dockerfile-linter.sh
 
-docker-example-run: # Run Docker example
+docker-example-run: # Run Docker example @ExamplesAndTests
 	source scripts/docker/docker.lib.sh
 	cd scripts/docker/examples/python
 	DOCKER_IMAGE=repository-template/docker-example-python
@@ -55,7 +61,7 @@ docker-example-run: # Run Docker example
 	"
 	docker-run
 
-docker-example-clean: # Remove Docker example resources
+docker-example-clean: # Remove Docker example resources @ExamplesAndTests
 	source scripts/docker/docker.lib.sh
 	cd scripts/docker/examples/python
 	DOCKER_IMAGE=repository-template/docker-example-python

scripts/docker/docker.mk

@@ -27,7 +27,8 @@ function main() {
   test-docker-suite-setup
   tests=( \
     test-docker-build \
-    test-docker-version \
+    test-docker-image-from-signature \
+    test-docker-version-file \
     test-docker-test \
     test-docker-run \
     test-docker-clean \
@@ -70,7 +71,17 @@ function test-docker-build() {
   docker image inspect "${DOCKER_IMAGE}:$(_get-effective-version)" > /dev/null 2>&1 && return 0 || return 1
 }
 
-function test-docker-version() {
+function test-docker-image-from-signature() {
+
+  # Arrange
+  cp Dockerfile Dockerfile.effective
+  # Act
+  _replace-image-latest-by-specific-version
+  # Assert
+  grep -q "FROM python:.*-alpine.*@sha256:.*" Dockerfile.effective && return 0 || return 1
+}
+
+function test-docker-version-file() {
 
   # Arrange
   export BUILD_DATETIME="2023-09-04T15:46:34+0000"