blob: 1aa69f529f5f4c0203e8b2f621c4ed835d6c1e21 [file] [log] [blame]
Joey Armstrong36592e32022-11-28 09:00:28 -05001# -*- makefile -*-
2# -----------------------------------------------------------------------
Joey Armstrong9f7c57c2024-05-03 18:29:30 -04003# Copyright 2022-2024 Open Networking Foundation Contributors
Joey Armstrong36592e32022-11-28 09:00:28 -05004#
5# Licensed under the Apache License, Version 2.0 (the "License");
6# you may not use this file except in compliance with the License.
7# You may obtain a copy of the License at
8#
9# http://www.apache.org/licenses/LICENSE-2.0
10#
11# Unless required by applicable law or agreed to in writing, software
12# distributed under the License is distributed on an "AS IS" BASIS,
13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14# See the License for the specific language governing permissions and
15# limitations under the License.
16# -----------------------------------------------------------------------
Joey Armstrong9f7c57c2024-05-03 18:29:30 -040017# SPDX-FileCopyrightText: 2022-2024 Open Networking Foundation Contributors
18# SPDX-License-Identifier: Apache-2.0
19# -----------------------------------------------------------------------
20# Intent: Makefile for Sphinx documentation
21# -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070022
Joey Armstrong9f7c57c2024-05-03 18:29:30 -040023ifndef .DEFAULT_GOAL
24 .DEFAULT_GOAL := help # ?= help evaluated late
25endif
26MAKECMDGOALS ?= help
Joey Armstrong36592e32022-11-28 09:00:28 -050027
Joey Armstrong9f7c57c2024-05-03 18:29:30 -040028$(if $(findstring disabled-joey,$(USER)),\
29 $(eval USE_LF_MK := 1)) # special snowflake
Joey Armstrong36592e32022-11-28 09:00:28 -050030
31##--------------------##
32##---] INCLUDES [---##
33##--------------------##
Joey Armstrong9f7c57c2024-05-03 18:29:30 -040034ifdef USE_LF_MK
35 include lf/include.mk
36else
37 include lf/transition.mk
38endif # ifdef USE_LF_MK
Zack Williams071eda22019-05-15 18:19:51 -070039
40# You can set these variables from the command line.
41SPHINXOPTS ?=
42SPHINXBUILD ?= sphinx-build
43SOURCEDIR ?= .
44BUILDDIR ?= _build
45
Zack Williams88df4742019-12-20 08:24:47 -070046# Other repos with documentation to include.
47# edit the `git_refs` file with the commit/tag/branch that you want to use
Andrea Campanellac18d1182021-09-10 12:01:38 +020048OTHER_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
Zack Williams88df4742019-12-20 08:24:47 -070049
Joey Armstrong36592e32022-11-28 09:00:28 -050050ifdef NO_OTHER_REPO_DOCS
51 # Inhibit pulling in external repos.
52 # python 3.10+ patching not supported by all repos yet.
53 OTHER_REPO_DOCS := $(null)
54endif
55
Zack Williams16042b62020-03-29 22:03:16 -070056# Static docs, built by other means (usually robot framework)
57STATIC_DOCS := _static/voltha-system-tests _static/cord-tester
58
Joey Armstrong4de98b72023-02-09 14:51:38 -050059# Why is existing source Makefile PHONY (?)
Zack Williams88df4742019-12-20 08:24:47 -070060.PHONY: help test lint reload Makefile prep
Zack Williams071eda22019-05-15 18:19:51 -070061
Joey Armstrong4de98b72023-02-09 14:51:38 -050062## -----------------------------------------------------------------------
Joey Armstrong721519c2023-11-13 15:30:54 -050063## Intent: Display makefile target help
64## -----------------------------------------------------------------------
65help :: help-targets-main
66help-verbose :: help-targets-sphinx
67
68## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -050069## Intent: Real time viewing, dynamically generate and reload document
70## changes for web browser viewing.
71## Usage:
72## make reload
73## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -040074reload: $(venv-activate-patched)
Joey Armstrong4de98b72023-02-09 14:51:38 -050075 $(activate) && sphinx-reload $(SOURCEDIR)
Zack Williams071eda22019-05-15 18:19:51 -070076
Joey Armstrong8d62cd92022-12-22 13:53:48 -050077## -----------------------------------------------------------------------
78## Intent: lint and link verification. linkcheck is part of sphinx
Joey Armstrong64b82492023-06-01 17:34:39 -040079## See Also: make test-errors
Joey Armstrong8d62cd92022-12-22 13:53:48 -050080## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070081test: lint linkcheck
Joey Armstronga8bc8e12022-12-04 07:06:59 -050082
Joey Armstrong50895b82023-09-14 16:44:28 -040083# [TODO] relocate into repo:onf-make/
84lint : $(venv-activate-patched)
85linkcheck : $(venv-activate-patched)
86
Joey Armstrong8d62cd92022-12-22 13:53:48 -050087## -----------------------------------------------------------------------
88## Intent: Exercise all generation targets
Joey Armstrong4de98b72023-02-09 14:51:38 -050089## Bridge: library workaround to support legacy targets
Joey Armstrong8d62cd92022-12-22 13:53:48 -050090## -----------------------------------------------------------------------
91test-all-targets += html
92test-all-targets += coverage
93# test-all-targets += changes
94# test-all-targets += info
95test-all-targets += man
96test-all-targe4ts += text
97# test-all-targets += latex
98
Joey Armstrong8d62cd92022-12-22 13:53:48 -050099test-all : test
100 $(MAKE) $(test-all-targets)
101
Joey Armstrong36592e32022-11-28 09:00:28 -0500102# doctest
103# coverage
104# linkcheck
Zack Williams071eda22019-05-15 18:19:51 -0700105
Joey Armstrong0cbee512023-10-18 15:39:24 -0400106# -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700107# currently not enabled, should be added to lint target
Joey Armstrong0cbee512023-10-18 15:39:24 -0400108# [TODO] Create repo:onf-make/makefiles/lint/mdl
109# -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700110LINT_STYLE ?= mdl_strict.rb
111md-lint: | $(OTHER_REPO_DOCS)
112 @echo "markdownlint(mdl) version: `mdl --version`"
113 @echo "style config:"
114 @echo "---"
115 @cat $(LINT_STYLE)
116 @echo "---"
Joey Armstrong4de98b72023-02-09 14:51:38 -0500117 mdl -s $(LINT_STYLE) `find -L $(SOURCEDIR) ! -path "./_$(venv-activate-script)/*" ! -path "./_build/*" ! -path "./repos/*" ! -path "*vendor*" -name "*.md"`
Zack Williams071eda22019-05-15 18:19:51 -0700118
119# clean up
Joey Armstrong64b82492023-06-01 17:34:39 -0400120clean ::
Joey Armstrong36592e32022-11-28 09:00:28 -0500121 $(RM) -r $(BUILDDIR) $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Zack Williams071eda22019-05-15 18:19:51 -0700122
Joey Armstrong4de98b72023-02-09 14:51:38 -0500123clean-all sterile :: clean
124 $(RM) -r $(venv-activate-script) repos
Zack Williams071eda22019-05-15 18:19:51 -0700125
Zack Williams071eda22019-05-15 18:19:51 -0700126# checkout the repos inside repos/ dir
127repos:
128 mkdir repos
129
130# build directory paths in repos/* to perform 'git clone <repo>' into
131CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
132
133# Host holding the git server
134REPO_HOST ?= https://gerrit.opencord.org
135
136# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
137# pre-populate it under repos/ with the specific commit to being validated
138SKIP_CHECKOUT ?=
139
Zack Williams88df4742019-12-20 08:24:47 -0700140# clone (only if doesn't exist)
Zack Williams071eda22019-05-15 18:19:51 -0700141$(CHECKOUT_REPOS): | repos
Zack Williams071eda22019-05-15 18:19:51 -0700142 if [ ! -d '$@' ] ;\
143 then git clone $(REPO_HOST)/$(@F) $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700144 fi
145
Joey Armstrong4de98b72023-02-09 14:51:38 -0500146## -----------------------------------------------------------------------
147## Intent: checkout correct ref if not under test, then copy
148## subdirectories into main docs dir
149## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700150$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
Zack Williams88df4742019-12-20 08:24:47 -0700151 if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
152 then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700153 cd "repos/$@" && git checkout $$GIT_REF ;\
Zack Williams88df4742019-12-20 08:24:47 -0700154 fi
Zack Williams17e34022019-12-20 13:51:54 -0700155 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
Zack Williams33085522020-02-28 11:41:01 -0700156 cp -r repos/$(@)$$GIT_SUBDIR $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700157
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100158# Build Robot documentation in voltha-system-tests and copy it into _static.
159_static/voltha-system-tests: | $(OTHER_REPO_DOCS)
160 make -C voltha-system-tests gendocs
161 mkdir -p $@
162 cp -r voltha-system-tests/gendocs/* $@
163
Andy Bavier39d67b12020-02-27 16:08:52 -0700164# Build Robot documentation in cord-tester and copy it into _static.
165_static/cord-tester: | $(OTHER_REPO_DOCS)
166 make -C cord-tester gendocs
167 mkdir -p $@
168 cp -r cord-tester/gendocs/* $@
169
Joey Armstrong4de98b72023-02-09 14:51:38 -0500170## -----------------------------------------------------------------------
171## Intent: generate a list of git checksums suitable for updating git_refs
172## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700173freeze: repos
174 @for repo in $(OTHER_REPO_DOCS) ; do \
175 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700176 cd "repos/$$repo" > /dev/null ;\
Zack Williams071eda22019-05-15 18:19:51 -0700177 HEAD_SHA=`git rev-parse HEAD` ;\
178 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700179 cd ../.. ;\
Zack Williams071eda22019-05-15 18:19:51 -0700180 done
181
Joey Armstrong4de98b72023-02-09 14:51:38 -0500182## -----------------------------------------------------------------------
183## Intent: build multiple versions
184## -----------------------------------------------------------------------
Joey Armstrong7be65812023-09-29 18:35:31 -0400185multiversion: $(venv-activate-patched) Makefile | prep $(OTHER_REPO_DOCS)
Joey Armstrong4de98b72023-02-09 14:51:38 -0500186 $(activate)\
187 && sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
Zack Williams16042b62020-03-29 22:03:16 -0700188 cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
Zack Williams88df4742019-12-20 08:24:47 -0700189
Joey Armstrong4de98b72023-02-09 14:51:38 -0500190## -----------------------------------------------------------------------
191## Intent: used in sphinx-multiversion to properly link
192## -----------------------------------------------------------------------
Zack Williams16042b62020-03-29 22:03:16 -0700193prep: | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Andy Bavier5dee6ae2020-01-29 16:03:40 -0700194
Joey Armstrong4de98b72023-02-09 14:51:38 -0500195## -----------------------------------------------------------------------
196## Intent: Forward sphinx supported targets to sphinxbuild.
197## Bridge: legacy makefile wildcard rule forwarded unknown targets to sphinx.
198## library makefiles do more so transfer control only when needed.
199## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -0400200include $(ONF_MAKEDIR)/voltha/docs-catchall-targets.mk
Joey Armstrong7be65812023-09-29 18:35:31 -0400201voltha-docs-catchall : $(voltha-docs-catchall)
202$(voltha-docs-catchall): $(venv-activate-patched) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Joey Armstrong36592e32022-11-28 09:00:28 -0500203 @echo " ** CATCHALL: $@"
Joey Armstrong4de98b72023-02-09 14:51:38 -0500204 $(activate)\
205 && $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Joey Armstrong36592e32022-11-28 09:00:28 -0500206
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500207## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500208## Intent: Display makefile target help
209## -----------------------------------------------------------------------
Joey Armstrong721519c2023-11-13 15:30:54 -0500210help-targets-sphinx : $(venv-activate-patched)
Joey Armstrong4de98b72023-02-09 14:51:38 -0500211 @ echo
Joey Armstrong721519c2023-11-13 15:30:54 -0500212 @echo '[HELP: Sphinx]'
Joey Armstrong4de98b72023-02-09 14:51:38 -0500213 $(HIDE)$(activate) \
214 && $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
215
216## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400217## Intent: Display WARNINGS buried in sphinx output
218## -----------------------------------------------------------------------
219warnings-log := warnings.log
Joey Armstrong4f93b762023-06-06 08:36:02 -0400220warnings: sterile
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400221 $(MAKE) html 2>&1 \
222 | sed -e 's@\([Ww][Aa][Rr][Nn][Ii][Nn][Gg]\)@\n\1@g' \
223 > "$(warnings-log)"
Joey Armstrong4f93b762023-06-06 08:36:02 -0400224 grep 'WARNING' $(warnings-log)
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400225
Joey Armstrong4f93b762023-06-06 08:36:02 -0400226## -----------------------------------------------------------------------
227## Intent: Summarize linkcheck failures
228## -----------------------------------------------------------------------
229.PHONY: broken-log
230broken-log := broken.log
231broken-log : sterile
232 $(MAKE) linkcheck 2>&1 | tee "$(broken-log)"
233 ! grep broken "$(broken-log)"
234 grep -i error _build/linkcheck/output.txt
235
236## -----------------------------------------------------------------------
Joey Armstronge03bc602024-02-09 17:26:27 -0500237## Intent: Summarize linkcheck failures
238## -----------------------------------------------------------------------
239.PHONY: lint-doc8-debug
240lint-doc8-debug : sterile
241 $(HIDE) @echo "Searching for cryptic failures"
242 -grep -i 'X <' release_notes/voltha_2.12.rst | grep -v '`__'
243
244## -----------------------------------------------------------------------
Joey Armstrong4f93b762023-06-06 08:36:02 -0400245## Intent:
246## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400247clean::
Joey Armstrong4f93b762023-06-06 08:36:02 -0400248 $(RM) $(broken-log)
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400249 $(RM) $(warnings-log)
250
Joey Armstrong4f93b762023-06-06 08:36:02 -0400251## -----------------------------------------------------------------------
252## Intent:
253## -----------------------------------------------------------------------
Joey Armstrong721519c2023-11-13 15:30:54 -0500254help :: help-targets-main
255help-targets-main :
256
257 @echo
258 @echo '[HELP]'
259 @printf ' %-30.30s %s\n' 'help' \
260 'Summary makefile target help'
261 @printf ' %-30.30s %s\n' 'help-verbose' \
262 'Extended makefile target help'
263
264 @echo
Joey Armstrong9f7c57c2024-05-03 18:29:30 -0400265 @echo '[INIT]'
Joey Armstrong721519c2023-11-13 15:30:54 -0500266 @printf ' %-30.30s %s\n' 'init' \
267 'Alias for git-submodules'
268 @printf ' %-30.30s %s\n' 'git-submodules' \
269 'Checkout external dependent repositories'
270
271 @echo
272 @echo '[TEST: Failures]'
273 @printf ' %-30.30s %s\n' 'broken' \
274 'Display broken URLs detected in linkcheck output'
275 @printf ' %-30.30s %s\n' 'warnings' \
276 'Display WARNING strings buried in sphinx output'
277
278## -----------------------------------------------------------------------
279## Intent: Checkout external repository dependencies
280## -----------------------------------------------------------------------
281init :: git-submodules
282
283git-submodules:
284 git submodule update --init --recursive
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400285
286## -----------------------------------------------------------------------
Joey Armstrong9f7c57c2024-05-03 18:29:30 -0400287## Intent: Display make help footer
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500288## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -0400289include $(ONF_MAKEDIR)/help/trailer.mk
Joey Armstrong36592e32022-11-28 09:00:28 -0500290
291# [EOF]