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