VOL-4977 - Failure in voltha-protos verification job.

Makefile
--------
 o This patch contains prototyping.
 o Define DISTUTILS_DEBUG to enable verbose output from python pkg install.
 o Define DOCKER_DEBUG to enable docker --debug.
 o Added whitespace to improve make output readability.
 o Insert banner text into targets so they will announce themselves for logging.
 o Remove @/$(HIDE) from prototype generation so command will be visible.

makefiles/docker/include.mk
---------------------------
 o Conditionally test for stdin and explicity pass --tty so docker can pass back log output.

.gitignore
----------
Ignore the virtualenv directory.

Change-Id: If73870fec03eadef2671f3f2f33075d58327914d
diff --git a/.gitignore b/.gitignore
index 1bd5b4e..8a1cfba 100755
--- a/.gitignore
+++ b/.gitignore
@@ -3,8 +3,8 @@
 *.egg-info
 dist
 build
+.venv
 .tox
-venv_protos
 
 # go related
 go_temp
diff --git a/Makefile b/Makefile
index 09c2531..b7673e0 100755
--- a/Makefile
+++ b/Makefile
@@ -31,6 +31,7 @@
 ##--------------------------
 # https://docs.python.org/3/distutils/setupscript.html#debugging-the-setup-script
 export DISTUTILS_DEBUG := 1
+export DOCKER_DEBUG    := 1
 
 # Makefile for voltha-protos
 default: test
@@ -63,7 +64,7 @@
 PROTO_GO_DEST_DIR := go
 PROTO_GO_PB:= $(foreach f, $(PROTO_FILES), $(patsubst protos/voltha_protos/%.proto,$(PROTO_GO_DEST_DIR)/$(call go_package_path,$(f))/%.pb.go,$(f)))
 PROTO_JAVA_DEST_DIR := java
-PROTO_JAVA_PB := $(foreach f, $(PROTO_FILES), $(patsubst protos/voltha_protos/%.proto,$(PROTO_JAVA_DEST_DIR)/$(call java_package_path,$(f))/%.pb.java,$(f))) 
+PROTO_JAVA_PB := $(foreach f, $(PROTO_FILES), $(patsubst protos/voltha_protos/%.proto,$(PROTO_JAVA_DEST_DIR)/$(call java_package_path,$(f))/%.pb.java,$(f)))
 
 # Force pb file to be regenrated every time.  Otherwise the make process assumes generated version is still valid
 .PHONY: voltha.pb
@@ -94,8 +95,13 @@
   protos/voltha_protos/%.proto \
   Makefile \
   $(venv-activate-script)
-	$(activate) \
-	&& python -m grpc_tools.protoc \
+
+	@echo
+	@echo "** -----------------------------------------------------------------------"
+	@echo "** $(MAKE): processing target [$@]"
+	@echo "** -----------------------------------------------------------------------"
+
+	$(activate) && python -m grpc_tools.protoc \
     -I protos \
     --python_out=python \
     --grpc_python_out=python \
@@ -104,13 +110,40 @@
     --include_source_info \
     $<
 
-python-build: setup.py python-protos
+## -----------------------------------------------------------------------
+## Intent:
+## -----------------------------------------------------------------------
+show:
+	$(call banner-enter,target $@)
+	@echo
+	$(call banner-leave,target $@)
+
+## -----------------------------------------------------------------------
+## Intent:
+## -----------------------------------------------------------------------
+python-build: setup.py python-protos	
+
+	$(call banner-enter,target $@)
+
 	$(RM) -r dist/
 	python ./setup.py sdist
 
+	$(call banner-leave,target $@)
+
+## -----------------------------------------------------------------------
+## Intent:
+## -----------------------------------------------------------------------
 python-test: tox.ini setup.py python-protos
+	$(call banner-enter,target $@)
+
+	$(activate) && python --version
 	tox
 
+	$(call banner-leave,target $@)
+
+## -----------------------------------------------------------------------
+## Intent:
+## -----------------------------------------------------------------------
 python-clean:
 	find python -name '__pycache__' -type d -print0 \
 	    | xargs -0 --no-run-if-empty $(RM) -r
@@ -147,11 +180,21 @@
 repair:
 	/usr/bin/env git checkout go
 
-
-# Go targets
+## -----------------------------------------------------------------------
+## Intent: Go targets
+## -----------------------------------------------------------------------
 go-protos: voltha.pb
-	@echo "Creating *.go.pb files"
+
+	@echo
+	@echo "** -----------------------------------------------------------------------"
+	@echo "** $(MAKE): processing target [$@]"
+	@echo "** Creating *.go.pb files"
+	@echo "** -----------------------------------------------------------------------"
+
+	@echo
 	@echo "PROTO_FILES=$(PROTO_FILES)" | tr ' ' '\n'
+
+	@echo
 	${PROTOC_SH} $(quote-double)\
 	  set -e -o pipefail; \
 	  for x in ${PROTO_FILES}; do \
@@ -159,20 +202,39 @@
 	    protoc --go_out=plugins=grpc:/go/src -I protos \$$x; \
 	  done$(quote-double)
 
+## -----------------------------------------------------------------------
+## Intent:
+## -----------------------------------------------------------------------
 voltha.pb:
-	@echo "Creating $@"
-	$(HIDE)${PROTOC} -I protos -I protos/google/api \
-	  --include_imports --include_source_info \
+	$(call banner-enter,target $@)
+
+	${PROTOC} \
+	  -I protos \
+	  -I protos/google/api \
+	  --include_imports \
+	  --include_source_info \
 	  --descriptor_set_out=$@ \
 	  ${PROTO_FILES}
 
+	$(call banner-leave,target $@)
+
+## -----------------------------------------------------------------------
+## Intent:
+## -----------------------------------------------------------------------
 go-test:
+	$(call banner-enter,target $@)
+
 	test/test-go-proto-consistency.sh
 	${GO} mod verify
 
-# Java targets
+	$(call banner-leave,target $@)
+
+## -----------------------------------------------------------------------
+## Intent: Java targets
+## -----------------------------------------------------------------------
 java-protos: voltha.pb
-	@echo "Creating java files"
+	$(call banner-enter,target $@)
+
 	@mkdir -p java_temp/src/main/java
 	@${PROTOC_SH} $(quote-double) \
 	  set -e -o pipefail; \
@@ -180,15 +242,25 @@
 	    echo \$$x; \
 	    protoc --java_out=java_temp/src/main/java -I protos \$$x; \
 	  done$(quote-double)
-        #TODO: generate directly to the final location
-	@mkdir -p java
-	cp -r java_temp/src/main/java/* java/
 
-# Tests if the generated java classes are compilable
+        # Move files into place after all prototypes have generated.
+        # TODO: Remove the extra step, use makefile deps and
+        #       generate in-place as needed.
+	@mkdir -p java
+	cp -r java_temp/src/main/java/* java
+
+	$(call banner-leave,target $@)
+
+## -----------------------------------------------------------------------
+## Intent: Tests if the generated java classes are compilable
+## -----------------------------------------------------------------------
 java-test: java-protos
 	cp test/pom.xml java_temp
 	cd java_temp && mvn compile
 
+## -----------------------------------------------------------------------
+## Intent: Custodial service
+## -----------------------------------------------------------------------
 java-clean:
 	$(RM) -r java
 	$(RM) -r java_temp
diff --git a/makefiles/docker/include.mk b/makefiles/docker/include.mk
index d78d008..3ed7d08 100644
--- a/makefiles/docker/include.mk
+++ b/makefiles/docker/include.mk
@@ -20,9 +20,18 @@
 # tool containers
 VOLTHA_TOOLS_VERSION ?= 2.4.0
 
-docker-run     = docker run --rm --user $$(id -u):$$(id -g)#   # Docker command stem
+docker-run     := docker
+ifdef DOCKER_DEBUG
+  docker-run   += --debug
+endif
+docker-run     += run --rm --user $$(id -u):$$(id -g)#   # Docker command stem
 docker-run-app = $(docker-run) -v ${CURDIR}:/app#              # w/filesystem mount
-is-stdin       = $(shell test -t 0 && echo "-it")
+
+## GhostBusters: Cross the streams
+## Always pass -it to attach streams, jenkins + docker == test -t fail
+# is-stdin       = $(shell test -t 0 && { echo "-it" } || {echo '--tty'})#    # Attach streams if interactive
+is-stdin       = $(shell test -t 0 && { echo '--interactive' })#              # Attach streams if interactive
+is-stdin       += --tty#                                                      # Attach stdout else jenkins::docker is silent
 
 # Docker volume mounts: container:/app/release <=> localhost:{pwd}/release
 vee-golang     = -v gocache-${VOLTHA_TOOLS_VERSION}:/go/pkg
diff --git a/makefiles/etc/include.mk b/makefiles/etc/include.mk
new file mode 100644
index 0000000..a48b42c
--- /dev/null
+++ b/makefiles/etc/include.mk
@@ -0,0 +1,48 @@
+# -*- makefile -*-
+# -----------------------------------------------------------------------
+# Copyright 2017-2023 Open Networking Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-FileCopyrightText: 2017-2023 Open Networking Foundation (ONF) and the ONF Contributors
+# SPDX-License-Identifier: Apache-2.0
+# -----------------------------------------------------------------------
+# Usage:
+#
+# mytarget:
+#     $(call banner-enter,target $@)
+#     @echo "Hello World"
+#     $(call banner-leave,target $@)
+# -----------------------------------------------------------------------
+
+$(if $(DEBUG),$(warning ENTER))
+
+target-banner = ** ---------------------------------------------------------------------------
+
+## -----------------------------------------------------------------------
+## Intent: Return a command line able to display a banner hilighting
+##         make target processing within a logfile.
+## -----------------------------------------------------------------------
+banner-enter=\
+    @echo -e \
+    "\n"\
+    "$(target-banner)\n"\
+    "** $(MAKE) ENTER: $(1)\n"\
+    "$(target-banner)"\
+
+banner-leave=\
+    @echo -e "** $(MAKE) LEAVE: $(1)"
+
+$(if $(DEBUG),$(warning LEAVE))
+
+# [EOF]
diff --git a/makefiles/include.mk b/makefiles/include.mk
index 3cdbf2c..2ce93de 100644
--- a/makefiles/include.mk
+++ b/makefiles/include.mk
@@ -35,6 +35,7 @@
 include $(MAKEDIR)/help/include.mk
 
 include $(MAKEDIR)/consts.mk
+include $(MAKEDIR)/etc/include.mk
 include $(MAKEDIR)/virtualenv.mk
 
 include $(MAKEDIR)/help/variables.mk
diff --git a/test/test-go-proto-consistency.sh b/test/test-go-proto-consistency.sh
index 4067d53..4653a13 100755
--- a/test/test-go-proto-consistency.sh
+++ b/test/test-go-proto-consistency.sh
@@ -32,9 +32,13 @@
     exit 1
 fi
 
+# TODO: Move this into the make clean target for one stop shopping.
 # delete and regenerate go protos
 rm -rf go/voltha.pb go/*/*.pb.go go_temp
+
+echo "$0: make go-protos: ENTER"
 make go-protos
+echo "$0: make go-protos: LEAVE"
 
 # Running git status ensures correct git diff-index picks up changes
 git status > /dev/null
@@ -50,3 +54,5 @@
     echo "Test successful. All go proto build outputs are committed"
     exit 0
 fi
+
+# [EOF]