[VOL-5194] - Refactor and use repo:onf-make as a git-submodule
makefiles/lint/doc8/doc8.ini
makefiles/lint/doc8/ini.mk
----------------------------
o Repo:onf-make library makefiles define a default config for doc8.
o Per-repository overrides and exclusions are needed for linting.
o The doc8 command will err when multiple --config switches are passed.
o ini.mk was added to dynamically generate a doc8.ini config
file by merging library and local doc8 configs.
config.mk
---------
o Added a deprecation note for config values moving to repo:voltha-docs.
o Explicitly define --repo-name--, we lose per-repository error checking
but the edit is needed to enable jenkins lint testing for repo:onf-make.
makefiles/include.mk
makefiles/.gitignore
--------------------
o Define onf-mk-tmp=makefiles/tmp for internal library makefile use.
o Targets and 'make clean' maintain the temp directory.
makefiles/lint/doc8/include.mk
------------------------------
o include ini.mk to generate a doc8.ini config file.
o Update lint target to support common *-{all, mod, src} targets.
o help targets: replace echo with printf for consistent formatting.
o Added banner-{enter,leave} calls and fixed a typo.
makefiles/lint/doc8/install.mk
------------------------------
o Rename peripheral doc8 help target to lint-doc8-help.
Output from 'make help' is growing long and difficult to read.
Simplify by displaying two help items per topic (primary and summary),
devs can later request topic specific help by name when needed.
Change-Id: I7c83bd48d26510e79fd32f8bb97887cace67b55f
diff --git a/.gitignore b/.gitignore
index b4cb667..bb2d999 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,8 @@
.venv/
__pycache__/
+tmp/
+
## Python patch creation
staging/
diff --git a/config.mk b/config.mk
index de65390..cf07bc2 100644
--- a/config.mk
+++ b/config.mk
@@ -19,7 +19,7 @@
# ONF.confg.mk = 1.5
# -----------------------------------------------------------------------
-# --repo-name-- :=
+--repo-name-- := onf-make
--repo-name-- ?= $(error --repo-name--= is required)
##--------------------------------##
@@ -76,7 +76,7 @@
onf-excl-dirs += .tox # also a python dependency
ifeq ($(--repo-name--),voltha-docs)
- lint-doc8-excl += '_build'
+ lint-doc8-excl += '_build' # TODO: deprecate
endif
onf-excl-dirs ?= $(error onf-excl-dirs= is required)
@@ -90,6 +90,7 @@
$(if $(filter %ci-management,$(--repo-name--)),\
$(eval --REPO-IS-CI-MANAGEMENT-- := true)\
)
+
$(if $(filter %voltha-docs,$(--repo-name--)),\
$(eval --REPO-IS-VOLTHA-DOCS-- := true)\
)
diff --git a/makefiles/include.mk b/makefiles/include.mk
index 746252c..1dba95f 100644
--- a/makefiles/include.mk
+++ b/makefiles/include.mk
@@ -25,16 +25,26 @@
$(if $(DEBUG),$(warning ENTER))
+##-------------------##
+##---] GLOBALS [---##
+##-------------------##
+
## -----------------------------------------------------------------------
## Define vars based on relative import (normalize symlinks)
## Usage: include makefiles/onf/include.mk
+## Overide-by: makefiles/onf-lib/makefiles/include.mk
+## when repo:onf-make is used as a git-submodule
## -----------------------------------------------------------------------
onf-mk-abs ?= $(abspath $(lastword $(MAKEFILE_LIST)))
onf-mk-top := $(subst /include.mk,$(null),$(onf-mk-abs))
+onf-mk-tmp := $(onf-mk-top)/tmp
ONF_MAKEDIR := $(onf-mk-top)
TOP ?= $(patsubst %/makefiles/include.mk,%,$(onf-mk-abs))
+##--------------------##
+##---] INCLUDES [---##
+##--------------------##
include $(ONF_MAKEDIR)/consts.mk
include $(ONF_MAKEDIR)/help/include.mk # render target help
include $(ONF_MAKEDIR)/utils/include.mk # dependency-less helper macros
diff --git a/makefiles/lint/doc8/doc8.ini b/makefiles/lint/doc8/doc8.ini
new file mode 100644
index 0000000..fd87fdc
--- /dev/null
+++ b/makefiles/lint/doc8/doc8.ini
@@ -0,0 +1,69 @@
+[doc8]
+
+## -----------------------------------------------------------------------
+# $ doc8 -h
+#
+# usage: doc8 [-h] [--config path] [--allow-long-titles] [--ignore code]
+# [--no-sphinx] [--ignore-path path] [--ignore-path-errors path]
+# [--default-extension extension] [--file-encoding encoding]
+# [--max-line-length int] [-e extension] [-v] [--version]
+# [path [path ...]]
+#
+# Check documentation for simple style requirements.
+#
+# What is checked:
+# - invalid RST format - D000
+# - lines should not be longer than 79 characters - D001
+# - RST exception: line with no whitespace except in the beginning
+# - RST exception: lines with http or https urls
+# - RST exception: literal blocks
+# - RST exception: rst target directives
+# - no trailing whitespace - D002
+# - no tabulation for indentation - D003
+# - no carriage returns (use unix newlines) - D004
+# - no newline at end of file - D005
+#
+# positional arguments:
+# path Path to scan for doc files (default: current
+# directory).
+#
+# optional arguments:
+# -h, --help show this help message and exit
+# --config path user config file location (default: .config/doc8.ini, doc8.ini, tox.ini,
+# pep8.ini, setup.cfg).
+# --allow-long-titles allow long section titles (default: false).
+# --ignore code ignore the given error code(s).
+# --no-sphinx do not ignore sphinx specific false positives.
+# --ignore-path path ignore the given directory or file (globs are
+# supported).
+# --ignore-path-errors path
+# ignore the given specific errors in the provided file.
+# --default-extension extension
+# default file extension to use when a file is found
+# without a file extension.
+# --file-encoding encoding
+# set input files text encoding
+# --max-line-length int
+# maximum allowed line length (default: 79).
+# -e extension, --extension extension
+# check file extensions of the given type (default:
+# .rst, .txt).
+# -q, --quiet only print violations
+# -v, --verbose run in verbose mode.
+# --version show the version and exit.
+## -----------------------------------------------------------------------
+
+# verbose=1
+
+extension = rst, txt
+ignore-path = .venv, */.venv
+
+# ignore-path-errors=/tmp/other_thing.rst;D001;D002
+# voltha-helm-charts/voltha-infra/templates/NOTES.txt:12: D001 Line too long
+
+max-line-length = 120
+
+# [SEE ALSO]
+# -----------------------------------------------------------------------
+# https://doc8.readthedocs.io/en/latest/readme.html
+# -----------------------------------------------------------------------
diff --git a/makefiles/lint/doc8/include.mk b/makefiles/lint/doc8/include.mk
index 564fca9..8d784d4 100644
--- a/makefiles/lint/doc8/include.mk
+++ b/makefiles/lint/doc8/include.mk
@@ -14,6 +14,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
# -----------------------------------------------------------------------
+# NOTE: The doc8 command runs recursively on directories so targets
+# *-mod and *-src are not yet supported.
+# -----------------------------------------------------------------------
##--------------------##
##---] INCLUDES [---##
diff --git a/makefiles/lint/doc8/ini.mk b/makefiles/lint/doc8/ini.mk
new file mode 100644
index 0000000..37a57ec
--- /dev/null
+++ b/makefiles/lint/doc8/ini.mk
@@ -0,0 +1,85 @@
+# -*- makefile -*-
+# -----------------------------------------------------------------------
+# Copyright 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.
+# -----------------------------------------------------------------------
+
+##-------------------##
+##---] GLOBALS [---##
+##-------------------##
+.PHONY: lint-doc8-ini-tmp
+
+lint-doc8-ini-tmp = $(onf-mk-tmp)/doc8.ini
+.DELETE_ON_ERROR : $(lint-doc8-ini-tmp)
+.PHONY : lint-doc8-ini-tmp $(lint-doc8-ini-tmp)
+
+lint-doc8-ini-tmp : $(lint-doc8-ini-tmp)
+
+# -----------------------------------------------------------------------
+# Intent: Doc8(s) --config switch will only accept one argument and
+# configs/exclusions are needed from multiple sources.
+# This target will merge doc8.ini from onf-make/ and local/ for use.
+# -----------------------------------------------------------------------
+# repo:onf-make is special, MAKEDIR=makefiles/local does not exist.
+# -----------------------------------------------------------------------
+lint-doc8-ini-raw := $(ONF_MAKEDIR)/lint/doc8/doc8.ini
+ifneq ($(--repo-name--),onf-make)
+ lint-doc8-ini-raw += $(MAKEDIR)/lint/doc8/doc8.ini
+endif
+
+lint-doc8-ini-src = $(wildcard $(lint-doc8-ini-raw))
+$(lint-doc8-ini-tmp):
+
+ $(call banner,Target $@)
+
+ @echo "FILES: $(lint-doc8-ini-src)"
+ mkdir -p $(dir $@)
+
+ @echo "** [doc8.ini] Generate $@"
+ @echo '[doc8]' > $@
+
+ @echo '** [doc8.ini] Merge onf-make and local config options'
+ $(HIDE)grep -v --fixed-strings --no-filename \
+ -e '[doc8]' \
+ -e 'ignore-path' \
+ -e 'max-line-length' \
+ $(lint-doc8-ini-src) \
+ >> $@
+
+ @echo '** [doc8.ini] Construct ignore-path='
+ @echo -n 'ignore-path = ' >> $@
+ $(HIDE)awk -F'=' '/^ignore-path/ {print $$2}' $(lint-doc8-ini-src) \
+ | paste -sd ',' - \
+ >> $@
+
+# # Prefer local config setting
+ @echo '** [doc8.ini] Extract max-line-length'
+ $(HIDE)grep --fixed-strings --no-filename 'max-line-length' $(lint-doc8-ini-src) \
+ | tail -n 1 \
+ >> $@
+
+ $(if $(DEBUG),cat $@)
+
+# -----------------------------------------------------------------------
+# -----------------------------------------------------------------------
+clean ::
+ $(RM) $(lint-doc8-ini-tmp)
+
+# -----------------------------------------------------------------------
+# -----------------------------------------------------------------------
+lint-doc8-help ::
+ @printf ' %-25.25s %s\n' 'lint-doc8-ini-tmp' \
+ 'Create doc8.ini from onf-make/ and local/'
+
+# [EOF]
diff --git a/makefiles/lint/doc8/install.mk b/makefiles/lint/doc8/install.mk
index 0e62260..98a36fd 100644
--- a/makefiles/lint/doc8/install.mk
+++ b/makefiles/lint/doc8/install.mk
@@ -59,7 +59,7 @@
## -----------------------------------------------------------------------
## Intent: Display command usage
## -----------------------------------------------------------------------
-help::
- @echo ' lint-doc8-install Install the doc8 tool'
+lint-doc8-help ::
+ @printf ' %-25.25s %s\n' 'lint-doc8-install' 'Install the doc8 tool'
# [EOF]