Makefile edits to improve library lint target support.

Makefile
--------
  o Replace inlined includes with single $(MAKEDIR)/include.mk
  o virtualenv install w/dependencies handled by makefiles/virtualenv.mk
  o Use '&&' for command separation to improve error handling.
  o Added more target documentation.
  o Re-home doc8/rst syntax checking into makefiles/lint/doc8.mk.

howto/code/linting.rst
----------------------
  o Document supported lint targets on docs.voltha.org.

howto/release/index.rst
howto/release/post-release/
howto/release/vcs/
---------------------------
  o Document more release related activity (bugfix branch creation)

makefiles/consts.mk
-------------------
  o Define and use more library macros.

config.mk
---------
  o Per-repository library makefile configuration, disable linting.

makefiles/virtualenv.mk
-----------------------
  o Library virtualenv install with dependences.
  o Begin using a consistent install directory.
  o Ugh: repository (voltha-docs) submodules each install a full venv.
  o Install dependency drive based on existence of activate script.
  o Lint targets updated to use activate script as a dependency.
  o Update activate macro to run:  set -u && activate && set +u

makefiles/patches/include.mk
----------------------------
  o Update to use virtualenv.mk defined macros.

makefiles/lint/doc8.mk
makefiles/lint/python/flake8.mk
makefiles/lint/json.mk
makefiles/lint/python/pylint.mk
makefiles/lint/robot.mk
makefiles/lint/shell.mk
makefiles/lint/yaml.mk
-------------------------------
  o All library linting defines consistent targets and logic.
  o Support two library targets: lint-all and lint-modified.
  o Default to checking all available sources.
  o Linting can be disabled per-repository via {project}/config.mk

Change-Id: I7b7b5e523c867183d44244a0da21cfa3584e9a50
diff --git a/Makefile b/Makefile
index ba5bba0..0ae2243 100644
--- a/Makefile
+++ b/Makefile
@@ -26,10 +26,8 @@
 ##--------------------##
 ##---]  INCLUDES  [---##
 ##--------------------##
-include $(MAKEDIR)/consts.mk
-include $(MAKEDIR)/help/include.mk
-include $(MAKEDIR)/patches/include.mk
-include $(MAKEDIR)/help/variables.mk
+-include config.mk
+include $(MAKEDIR)/include.mk
 
 # You can set these variables from the command line.
 SPHINXOPTS   ?=
@@ -50,43 +48,17 @@
 # Static docs, built by other means (usually robot framework)
 STATIC_DOCS    := _static/voltha-system-tests _static/cord-tester
 
-# name of python virtualenv that is used to run commands
-VENV_NAME      := venv_docs
-
+# Why is existing source Makefile PHONY (?)
 .PHONY: help test lint reload Makefile prep
 
-# Put it first so that "make" without argument is like "make help".
-help :: $(VENV_NAME)
-	@ echo
-	@ source $</bin/activate ; set -u ;\
-	$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-# -----------------------------------------------------------------------
-# Create the virtualenv with all the tools installed
-# -----------------------------------------------------------------------
-.PHONY: venv
-venv: $(VENV_NAME)
-
-$(VENV_NAME):
-	@echo
-	@echo "============================="
-	@echo "Installing python virtual env"
-	@echo "============================="
-	virtualenv -p python3 $@ ;\
-	source ./$@/bin/activate ;\
-	python -m pip install -r requirements.txt
-ifndef NO_PATCH
-	@echo
-	@echo "========================================"
-	@echo "Applying python virtualenv patches as needed (v3.10+)"
-	@echo "========================================"
-	./patches/python_310_migration.sh '--venv' "$@" 'apply'
-endif
-
-# automatically reload changes in browser as they're made
-reload: $(VENV_NAME)
-	source $</bin/activate ; set -u ;\
-	sphinx-reload $(SOURCEDIR)
+## -----------------------------------------------------------------------
+## Intent: Real time viewing, dynamically generate and reload document
+##         changes for web browser viewing.
+## Usage:
+##   make reload
+## -----------------------------------------------------------------------
+reload: $(venv-activate-script)
+	$(activate) && sphinx-reload $(SOURCEDIR)
 
 ## -----------------------------------------------------------------------
 ## Intent: lint and link verification. linkcheck is part of sphinx
@@ -95,6 +67,7 @@
 
 ## -----------------------------------------------------------------------
 ## Intent: Exercise all generation targets
+## Bridge: library workaround to support legacy targets
 ## -----------------------------------------------------------------------
 test-all-targets += html
 test-all-targets += coverage
@@ -104,22 +77,13 @@
 test-all-targe4ts += text
 # test-all-targets += latex
 
-
 test-all : test
 	$(MAKE) $(test-all-targets)
 
 # doctest
 # coverage
 # linkcheck
-lint: doc8
-# include $(MAKEDIR)/lint/shell.mk
 
-doc8: $(VENV_NAME) | $(OTHER_REPO_DOCS)
-	source $</bin/activate ; set -u ;\
-	doc8 --max-line-length 119 \
-	     $$(find . -name \*.rst ! -path "*venv*" ! -path "*vendor*" ! -path "*repos*" )
-
-# markdown linting
 #  currently not enabled, should be added to lint target
 LINT_STYLE ?= mdl_strict.rb
 md-lint: | $(OTHER_REPO_DOCS)
@@ -128,14 +92,14 @@
 	@echo "---"
 	@cat $(LINT_STYLE)
 	@echo "---"
-	mdl -s $(LINT_STYLE) `find -L $(SOURCEDIR) ! -path "./_$(VENV_NAME)/*" ! -path "./_build/*" ! -path "./repos/*" ! -path "*vendor*" -name "*.md"`
+	mdl -s $(LINT_STYLE) `find -L $(SOURCEDIR) ! -path "./_$(venv-activate-script)/*" ! -path "./_build/*" ! -path "./repos/*" ! -path "*vendor*" -name "*.md"`
 
 # clean up
 clean:
 	$(RM) -r $(BUILDDIR) $(OTHER_REPO_DOCS) $(STATIC_DOCS)
 
-clean-all sterile: clean
-	$(RM) -r $(VENV_NAME) repos
+clean-all sterile :: clean
+	$(RM) -r $(venv-activate-script) repos
 
 # checkout the repos inside repos/ dir
 repos:
@@ -157,8 +121,10 @@
 	  then git clone $(REPO_HOST)/$(@F) $@ ;\
 	fi
 
-# checkout correct ref if not under test, then copy subdirectories into main
-# docs dir
+## -----------------------------------------------------------------------
+## Intent: checkout correct ref if not under test, then copy
+##         subdirectories into main docs dir
+## -----------------------------------------------------------------------
 $(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
 	if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
 	  then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
@@ -179,7 +145,9 @@
 	mkdir -p $@
 	cp -r cord-tester/gendocs/* $@
 
-# generate a list of git checksums suitable for updating git_refs
+## -----------------------------------------------------------------------
+## Intent: generate a list of git checksums suitable for updating git_refs
+## -----------------------------------------------------------------------
 freeze: repos
 	@for repo in $(OTHER_REPO_DOCS) ; do \
 	  GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
@@ -189,24 +157,29 @@
 	  cd ../.. ;\
 	done
 
-# build multiple versions
-multiversion: $(VENV_NAME) Makefile | prep $(OTHER_REPO_DOCS)
-	source $</bin/activate ; set -u ;\
-	sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
+## -----------------------------------------------------------------------
+## Intent: build multiple versions
+## -----------------------------------------------------------------------
+multiversion: $(venv-activate-script) Makefile | prep $(OTHER_REPO_DOCS)
+	$(activate)\
+ && sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
 	cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
 
-# prep target - used in sphinx-multiversion to properly link
+## -----------------------------------------------------------------------
+## Intent: used in sphinx-multiversion to properly link
+## -----------------------------------------------------------------------
 prep: | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-# %: $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
-
+## -----------------------------------------------------------------------
+## Intent: Forward sphinx supported targets to sphinxbuild.
+## Bridge: legacy makefile wildcard rule forwarded unknown targets to sphinx.
+##         library makefiles do more so transfer control only when needed.
+## -----------------------------------------------------------------------
 include $(MAKEDIR)/voltha/docs-catchall-targets.mk
-$(voltha-docs-catchall): $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
+$(voltha-docs-catchall): $(venv-activate-script) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
 	@echo " ** CATCHALL: $@"
-	source $</bin/activate ; set -u ;\
-	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(activate)\
+ && $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 ## -----------------------------------------------------------------------
 ## -----------------------------------------------------------------------
@@ -215,6 +188,15 @@
 	"$(BROWSER)" _build/html/index.html
 
 ## -----------------------------------------------------------------------
+## Intent: Display makefile target help
+## -----------------------------------------------------------------------
+help :: $(venv-activate-script)
+	@ echo
+	$(HIDE)$(activate) \
+ && $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+## -----------------------------------------------------------------------
+## Intent: Display make hel footer
 ## -----------------------------------------------------------------------
 include $(MAKEDIR)/help/trailer.mk