Makefile - voltha-docs - Gitiles

 # -*- makefile -*-
 # -----------------------------------------------------------------------
 # Copyright 2022-2023 Open Networking Foundation (ONF) and the ONF Contributors
 #
 # 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.
 # -----------------------------------------------------------------------
 # Makefile for Sphinx documentation

 .DEFAULT_GOAL := help

 TOP         ?= .
 MAKEDIR     ?= $(TOP)/makefiles

 $(if $(VERBOSE),$(eval export VERBOSE=$(VERBOSE))) # visible to include(s)

 ##--------------------##
 ##---]  INCLUDES  [---##
 ##--------------------##
 include $(MAKEDIR)/consts.mk
 include $(MAKEDIR)/help/include.mk
 include $(MAKEDIR)/patches/include.mk
 include $(MAKEDIR)/help/variables.mk

 # You can set these variables from the command line.
 SPHINXOPTS   ?=
 SPHINXBUILD  ?= sphinx-build
 SOURCEDIR    ?= .
 BUILDDIR     ?= _build

 # Other repos with documentation to include.
 # edit the `git_refs` file with the commit/tag/branch that you want to use
 OTHER_REPO_DOCS ?= bbsim cord-tester ofagent-go openolt voltctl voltha-openolt-adapter voltha-openonu-adapter-go voltha-protos voltha-system-tests device-management-interface voltha-helm-charts

 ifdef NO_OTHER_REPO_DOCS
   # Inhibit pulling in external repos.
   # python 3.10+ patching not supported by all repos yet.
   OTHER_REPO_DOCS := $(null)
 endif

 # 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

 .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: lint and link verification. linkcheck is part of sphinx
 ## -----------------------------------------------------------------------
 test: lint linkcheck

 ## -----------------------------------------------------------------------
 ## Intent: Exercise all generation targets
 ## -----------------------------------------------------------------------
 test-all-targets += html
 test-all-targets += coverage
 # test-all-targets += changes
 # test-all-targets += info
 test-all-targets += man
 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)
 	@echo "markdownlint(mdl) version: `mdl --version`"
 	@echo "style config:"
 	@echo "---"
 	@cat $(LINT_STYLE)
 	@echo "---"
 	mdl -s $(LINT_STYLE) `find -L $(SOURCEDIR) ! -path "./_$(VENV_NAME)/*" ! -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

 # checkout the repos inside repos/ dir
 repos:
 	mkdir repos

 # build directory paths in repos/* to perform 'git clone <repo>' into
 CHECKOUT_REPOS   = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))

 # Host holding the git server
 REPO_HOST       ?= https://gerrit.opencord.org

 # For QA patchset validation - set SKIP_CHECKOUT to the repo name and
 # pre-populate it under repos/ with the specific commit to being validated
 SKIP_CHECKOUT   ?=

 # clone (only if doesn't exist)
 $(CHECKOUT_REPOS): | repos
 	if [ ! -d '$@' ] ;\
 	  then git clone $(REPO_HOST)/$(@F) $@ ;\
 	fi

 # 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}'` ;\
 	  cd "repos/$@" && git checkout $$GIT_REF ;\
 	fi
 	GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
 	cp -r repos/$(@)$$GIT_SUBDIR $@ ;\

 # Build Robot documentation in voltha-system-tests and copy it into _static.
 _static/voltha-system-tests: | $(OTHER_REPO_DOCS)
 	make -C voltha-system-tests gendocs
 	mkdir -p $@
 	cp -r voltha-system-tests/gendocs/* $@

 # Build Robot documentation in cord-tester and copy it into _static.
 _static/cord-tester: | $(OTHER_REPO_DOCS)
 	make -C cord-tester gendocs
 	mkdir -p $@
 	cp -r cord-tester/gendocs/* $@

 # 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}'` ;\
 	  cd "repos/$$repo" > /dev/null ;\
 	    HEAD_SHA=`git rev-parse HEAD` ;\
 	    printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
 	  cd ../.. ;\
 	done

 # build multiple versions
 multiversion: $(VENV_NAME) Makefile | prep $(OTHER_REPO_DOCS)
 	source $</bin/activate ; set -u ;\
 	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
 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)

 include $(MAKEDIR)/voltha/docs-catchall-targets.mk
 $(voltha-docs-catchall): $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
 	@echo " ** CATCHALL: $@"
 	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]
	# -- makefile --
	# -----------------------------------------------------------------------
	# Copyright 2022-2023 Open Networking Foundation (ONF) and the ONF Contributors
	#
	# 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.
	# -----------------------------------------------------------------------
	# Makefile for Sphinx documentation

	.DEFAULT_GOAL := help

	TOP ?= .
	MAKEDIR ?= $(TOP)/makefiles

	$(if $(VERBOSE),$(eval export VERBOSE=$(VERBOSE))) # visible to include(s)

	##--------------------##
	##---] INCLUDES [---##
	##--------------------##
	include $(MAKEDIR)/consts.mk
	include $(MAKEDIR)/help/include.mk
	include $(MAKEDIR)/patches/include.mk
	include $(MAKEDIR)/help/variables.mk

	# You can set these variables from the command line.
	SPHINXOPTS ?=
	SPHINXBUILD ?= sphinx-build
	SOURCEDIR ?= .
	BUILDDIR ?= _build

	# Other repos with documentation to include.
	# edit the `git_refs` file with the commit/tag/branch that you want to use
	OTHER_REPO_DOCS ?= bbsim cord-tester ofagent-go openolt voltctl voltha-openolt-adapter voltha-openonu-adapter-go voltha-protos voltha-system-tests device-management-interface voltha-helm-charts

	ifdef NO_OTHER_REPO_DOCS
	# Inhibit pulling in external repos.
	# python 3.10+ patching not supported by all repos yet.
	OTHER_REPO_DOCS := $(null)
	endif

	# 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

	.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: lint and link verification. linkcheck is part of sphinx
	## -----------------------------------------------------------------------
	test: lint linkcheck

	## -----------------------------------------------------------------------
	## Intent: Exercise all generation targets
	## -----------------------------------------------------------------------
	test-all-targets += html
	test-all-targets += coverage
	# test-all-targets += changes
	# test-all-targets += info
	test-all-targets += man
	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)
	@echo "markdownlint(mdl) version: `mdl --version`"
	@echo "style config:"
	@echo "---"
	@cat $(LINT_STYLE)
	@echo "---"
	mdl -s $(LINT_STYLE) `find -L $(SOURCEDIR) ! -path "./_$(VENV_NAME)/" ! -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

	# checkout the repos inside repos/ dir
	repos:
	mkdir repos

	# build directory paths in repos/* to perform 'git clone <repo>' into
	CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))

	# Host holding the git server
	REPO_HOST ?= https://gerrit.opencord.org

	# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
	# pre-populate it under repos/ with the specific commit to being validated
	SKIP_CHECKOUT ?=

	# clone (only if doesn't exist)
	$(CHECKOUT_REPOS): \| repos
	if [ ! -d '$@' ] ;\
	then git clone $(REPO_HOST)/$(@F) $@ ;\
	fi

	# 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}'` ;\
	cd "repos/$@" && git checkout $$GIT_REF ;\
	fi
	GIT_SUBDIR=`grep '^$@ ' git_refs \| awk '{print $$2}'` ;\
	cp -r repos/$(@)$$GIT_SUBDIR $@ ;\

	# Build Robot documentation in voltha-system-tests and copy it into _static.
	_static/voltha-system-tests: \| $(OTHER_REPO_DOCS)
	make -C voltha-system-tests gendocs
	mkdir -p $@
	cp -r voltha-system-tests/gendocs/* $@

	# Build Robot documentation in cord-tester and copy it into _static.
	_static/cord-tester: \| $(OTHER_REPO_DOCS)
	make -C cord-tester gendocs
	mkdir -p $@
	cp -r cord-tester/gendocs/* $@

	# 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}'` ;\
	cd "repos/$$repo" > /dev/null ;\
	HEAD_SHA=`git rev-parse HEAD` ;\
	printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
	cd ../.. ;\
	done

	# build multiple versions
	multiversion: $(VENV_NAME) Makefile \| prep $(OTHER_REPO_DOCS)
	source $</bin/activate ; set -u ;\
	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
	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)

	include $(MAKEDIR)/voltha/docs-catchall-targets.mk
	$(voltha-docs-catchall): $(VENV_NAME) Makefile \| $(OTHER_REPO_DOCS) $(STATIC_DOCS)
	@echo " ** CATCHALL: $@"
	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]