VOL-4840 - docs.voltha.org edits
Makefile
patches/python_310_migration.sh
-------------------------------
o Change log message to note venv patching by version.
o Original message could be interpreted as explict patching of wrong version.
makefiles/lint/include.mk
-------------------------
o Document lint targets: usage, commands, makefiles, etc.
Change-Id: I895a0a032f856632c9adf31aa634b6cbf0328cdb
diff --git a/Makefile b/Makefile
index 289559c..908e7b2 100644
--- a/Makefile
+++ b/Makefile
@@ -78,7 +78,7 @@
ifndef NO_PATCH
@echo
@echo "========================================"
- @echo "Applying python 3.10.x migration patches"
+ @echo "Applying python virtualenv patches as needed (v3.10+)"
@echo "========================================"
./patches/python_310_migration.sh '--venv' "$@" 'apply'
endif
@@ -90,10 +90,12 @@
# lint and link verification. linkcheck is part of sphinx
test: lint linkcheck
+
# doctest
# coverage
# linkcheck
lint: doc8
+# include $(MAKEDIR)/lint/shell.mk
doc8: $(VENV_NAME) | $(OTHER_REPO_DOCS)
source $</bin/activate ; set -u ;\
@@ -189,6 +191,14 @@
source $</bin/activate ; set -u ;\
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+## -----------------------------------------------------------------------
+## -----------------------------------------------------------------------
+BROWSER ?= $(error Usage: $(MAKE) $@ BROWSER=)
+view-html:
+ "$(BROWSER)" _build/html/index.html
+
+## -----------------------------------------------------------------------
+## -----------------------------------------------------------------------
include $(MAKEDIR)/help/trailer.mk
# [EOF]
diff --git a/VERSION b/VERSION
index 9005dd0..6057b38 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.10.11
+2.10.12
diff --git a/howto/code/index.rst b/howto/code/index.rst
new file mode 100644
index 0000000..0d23582
--- /dev/null
+++ b/howto/code/index.rst
@@ -0,0 +1,8 @@
+Development & Source Code
+=========================
+
+.. toctree::
+ :maxdepth: 2
+
+ linting
+ pull_request
diff --git a/howto/code/linting.rst b/howto/code/linting.rst
new file mode 100644
index 0000000..e3619b2
--- /dev/null
+++ b/howto/code/linting.rst
@@ -0,0 +1,229 @@
+Source code syntax checking
+===========================
+
+Getting Started
+---------------
+
+.. code:: bash
+
+ git clone ssh://gerrit.opencord.org:29418/voltha-helm-charts.git
+ cd voltha-helm-charts
+
+ make help | grep lint
+ lint-chart chart_version_check.sh
+ lint-helm Syntax check helm configs
+ lint-json Syntax check json sources
+ lint-license Verify sources contain a license block.
+ lint-python Syntax check using pylint and flake8
+ lint-robot Syntax check robot sources using rflint
+ lint-shell Syntax check bash,bourne,etc sources
+ lint-yaml Syntax check yaml source using yamllint
+ UNSTABLE= Build targets prone to failure (lint-helm)
+
+|
+
+
+All Sources
++++++++++++
+
+The generic lint target can be used to invoke all defined lint targets.
+
+.. code:: bash
+
+ make clean
+ make lint 2>&1 | tee log
+
+|
+
+Helm Charts
++++++++++++
+
+Command(s):
+- `helmlint.sh <https://gerrit.opencord.org/plugins/gitiles/helm-repo-tools/+/refs/heads/master/helmlint.sh>`_
+
+.. code:: bash
+
+ make clean
+ make lint-chart lint-helm 2>&1 | tee log
+
+Sources:
+
+- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts/+/refs/heads/master/makefiles/lint/>`__
+- `makefiles/lint/helm.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts/+/refs/heads/master/makefiles/lint/helm.mk>`_
+- [`master <https://gerrit.opencord.org/plugins/gitiles/helm-repo-tools/+/refs/heads/master>`__] `helm-repo-tools <https://gerrit.opencord.org/plugins/gitiles/helm-repo-tools>`_
+
+|
+
+
+Golang
+++++++
+
+Command:
+
+Sources:
+
+- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/lint/>`__
+
+|
+
+JSON
+++++
+
+Command:
+- `json.tool <https://docs.python.org/3/library/json.html>`_
+
+.. code:: bash
+
+ make clean
+ make lint-json 2>&1 | tee log
+
+Sources:
+
+- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/lint/>`__
+- `makefiles/lint/json.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/lint/json.mk>`_
+
+|
+
+
+License / Copyright notice
+++++++++++++++++++++++++++
+
+Command:
+
+.. code:: bash
+
+ make clean
+ make lint-license 2>&1 | tee log
+
+Sources:
+
+- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/heads/master/makefiles/lint>`__
+- `makefiles/lint/license.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/heads/master/makefiles/lint/license/include.mk>`_
+
+|
+
+
+python
+++++++
+
+Command:
+- `flake8 <https://flake8.pycqa.org/en/latest>`_
+- `pylint <https://www.pylint.org/>`_
+
+.. code:: bash
+
+ make clean
+ make lint-python 2>&1 | tee log
+
+Sources:
+
+- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/lint/>`__
+- `makefiles/lint/python.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/lint/python.mk>`_
+- `makefiles/patches/include.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/patches/>`_
+
+Notes:
+
+- pylint --py3k options is no longer supported by v3.10+
+- lint-python target dependency will create a `python virtual env <https://wiki.opennetworking.org/display/JOEY/PythonVenv>`_
+- python 3.10+ requires `virtual env patching <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/patches/>`_
+
+|
+
+
+Robot
++++++
+
+Command: rflint
+
+Sources:
+
+- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/lint/>`__
+- `makefiles/lint/robot.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/heads/master/makefiles/lint/robot.mk>`_
+
+|
+
+
+reStructedTextFile (rst)
+++++++++++++++++++++++++
+
+Command: `doc8 <https://pypi.org/project/doc8/>`_
+
+Sources:
+
+- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/lint/>`__
+- `Makefiles::doc8 <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/Makefile#98>`_
+
+|
+
+
+Shell
++++++
+
+Command: `shellcheck <https://github.com/koalaman/shellcheck>`_
+
+Sources:
+
+- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/lint/>`__
+- `makefiles/lint/shell.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/heads/master/makefiles/lint/shell.mk>`_
+
+|
+
+
+Yaml
+++++
+
+Command: yamllint
+
+.. code:: bash
+
+ make clean
+ make lint-yaml 2>&1 | tee log
+
+Sources:
+
+- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles/lint/>`__
+- `makefiles/lint/yaml.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/heads/master/makefiles/lint/yaml.mk>`_
+
+|
+
+Makefile help
+~~~~~~~~~~~~~
+
+Individual Makefiles support a help targe that will display a list of
+targets and functionality supported.
+
+.. code:: bash
+
+ make help
+ make help-verbose
+ make help VERBOSE=1
+
+
+Bugs
+~~~~
+
+- `jira::VOLTHA <https://jira.opencord.org/projects/VOL>`-
+- Include repository URL
+- Include gerrit/github changeset if available.
+- A logfile snippet of the error and surrounding context.
+
+
+Repositories
+++++++++++++
+
+- [`master <https://gerrit.opencord.org/plugins/gitiles/bbsim/+/refs/heads/master>`__] `bbsim <https://gerrit.opencord.org/plugins/gitiles/bbsim>`_
+- [`master <https://gerrit.opencord.org/plugins/gitiles/pod-configs/+/refs/heads/master>`__] `pod-configs <https://gerrit.opencord.org/plugins/gitiles/pod-configs>`_
+- [`master <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master>`__] `voltha-docs <https://gerrit.opencord.org/plugins/gitiles/voltha-docs>`_
+- [`master <https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts/+/refs/heads/master>`__] `voltha-helm-charts <https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts>`_
+- [`master <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/heads/master>`__] `voltha-system-tests <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests>`_
+
+
+Notes
+~~~~~
+
+- Make lint complaints are not necessarily fatal.
+- Volume problem reports require cleanup before linting can become a default.
+- Lint target support is globally available across repositories, given time
+ it will be. Submit patches as needed or open a jira ticket to request
+ linting support in specific repositories.
+- Makefile refactoring: yes absolutely! Baby steps are needed in the interim...
diff --git a/howto/eof.rst b/howto/eof.rst
new file mode 100644
index 0000000..61c5d97
--- /dev/null
+++ b/howto/eof.rst
@@ -0,0 +1,2 @@
+EOF
+===
diff --git a/howto/index.rst b/howto/index.rst
index 0a898ec..0167429 100644
--- a/howto/index.rst
+++ b/howto/index.rst
@@ -4,6 +4,7 @@
.. toctree::
:maxdepth: 2
+ code/index
edit_voltha_docs
release/installVoltctl
voltha_repositories
diff --git a/index.rst b/index.rst
index 5ca5eaf..eae1574 100644
--- a/index.rst
+++ b/index.rst
@@ -208,3 +208,8 @@
:caption: HOWTO Topics
howto/index
+
+.. toctree::
+ :maxdepth: 0
+
+ howto/eof
diff --git a/makefiles/help/include.mk b/makefiles/help/include.mk
index 4264c52..0ff8bf4 100644
--- a/makefiles/help/include.mk
+++ b/makefiles/help/include.mk
@@ -21,13 +21,17 @@
@echo "Usage: $(MAKE) [options] [target] ..."
@echo
@echo '[Virtual Env]'
- @echo ' venv Create a python virtual environmen"
+ @echo ' venv Create a python virtual environment'
@echo " $(VENV_NAME)"
@echo
@echo '[CLEAN]'
@echo ' clean Remove generated targets'
@echo ' sterile clean + remove virtual env interpreter install'
@echo
+ @echo '[VIEW]'
+ @echo ' reload Setup to auto-reload sphinx doc changes in browser'
+ @echo ' view-html View generated documentation'
+ @echo
@echo '[HELP]'
@echo ' help Display program help'
@echo ' help-verbose Display additional targets and help'
diff --git a/makefiles/lint.mk b/makefiles/lint/include.mk
similarity index 95%
rename from makefiles/lint.mk
rename to makefiles/lint/include.mk
index cb4b0a7..979a6fb 100644
--- a/makefiles/lint.mk
+++ b/makefiles/lint/include.mk
@@ -22,6 +22,7 @@
include $(MAKEDIR)/lint/json.mk
include $(MAKEDIR)/lint/python.mk
include $(MAKEDIR)/lint/robot.mk
+include $(MAKEDIR)/lint/shell.mk
include $(MAKEDIR)/lint/yaml.mk
# [EOF]
diff --git a/makefiles/lint.mk b/makefiles/lint/shell.mk
similarity index 69%
copy from makefiles/lint.mk
copy to makefiles/lint/shell.mk
index cb4b0a7..da92921 100644
--- a/makefiles/lint.mk
+++ b/makefiles/lint/shell.mk
@@ -15,13 +15,19 @@
# limitations under the License.
# -----------------------------------------------------------------------
-help::
- @echo
- @echo "[LINT]"
+JSON_FILES ?= $(error JSON_FILES= is required)
-include $(MAKEDIR)/lint/json.mk
-include $(MAKEDIR)/lint/python.mk
-include $(MAKEDIR)/lint/robot.mk
-include $(MAKEDIR)/lint/yaml.mk
+.PHONY: lint-shell
+
+lint : lint-shell
+
+lint-shell:
+ shellcheck --version
+ find . \( -name 'staging' -o -name 'vst_venv' \) -prune \
+ -o -name '*.sh' ! -name 'activate.sh' -print0 \
+ | xargs -0 -n1 shellcheck
+
+help::
+ @echo " lint-shell Syntax check bash,bourne,etc sources"
# [EOF]
diff --git a/patches/python_310_migration.sh b/patches/python_310_migration.sh
index 12d7ca8..e324146 100755
--- a/patches/python_310_migration.sh
+++ b/patches/python_310_migration.sh
@@ -15,15 +15,44 @@
# limitations under the License.
# -----------------------------------------------------------------------
+##-------------------##
+##---] GLOBALS [---##
+##-------------------##
set -euo pipefail
-dst="vst_venv"
-src="staging"
-pat="patches"
+## -----------------------------------------------------------------------
+## Intent: Display script documentation.
+## -----------------------------------------------------------------------
+function show_help()
+{
+ cat <<EOH
+Usage: $0
+ apply Patch virtualenv python modules by version (3.10+).
+ backup Create a tarball for work-in-progress.
+ gather Display a list of potential source files to patch.
-declare -a fyls=()
+ --venv Installed venv directory to patch (override default)
+ --help This message
+
+See Also
+ patches/README.md Howto create a patch file.
+
+EOH
+ exit 0
+}
+
+##----------------##
+##---] MAIN [---##
+##----------------##
+declare dst="vst_venv"
+declare src="staging"
+declare pat="patches"
+
+## -----------------------
+## Slurp available patches
+## -----------------------
pushd "$pat" >/dev/null
-fyls+=( $(find . -name 'patch' -print) )
+readarray -t fyls < <(find . -name 'patch' -print)
popd >/dev/null
if [ $# -eq 0 ]; then set -- apply; fi
@@ -32,16 +61,9 @@
opt="$1"; shift
case "$opt" in
+ -*help) show_help ;;
-*venv) dst="$1"; shift ;;
- help)
- cat <<EOH
-apply - generate patches from vault source.
-backup - Archive patch directory
-gather - collect potential python files to edit.
-EOH
- ;;
-
apply)
pushd "$dst" >/dev/null || { echo "pushd $dst failed"; exit 1; }
for fyl in "${fyls[@]}";
@@ -76,7 +98,9 @@
done
find "$pat" -print
;;
-
+
+ help) show_help ;;
+
*)
echo "ERROR: Unknown action [$opt]"
exit 1