blob: 1648ba75c9473563054c53ad7de2aee48ee25d24 [file] [log] [blame]
Joey Armstrong36592e32022-11-28 09:00:28 -05001# -*- makefile -*-
2# -----------------------------------------------------------------------
Joey Armstrong8d62cd92022-12-22 13:53:48 -05003# Copyright 2022-2023 Open Networking Foundation (ONF) and the ONF 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# -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070017# Makefile for Sphinx documentation
18
Joey Armstrong36592e32022-11-28 09:00:28 -050019.DEFAULT_GOAL := help
20
Joey Armstrong449ce7a2023-07-18 18:32:24 -040021##-------------------##
22##---] GLOBALS [---##
23##-------------------##
Joey Armstrong50895b82023-09-14 16:44:28 -040024TOP ?=$(strip $(dir $(abspath $(lastword $(MAKEFILE_LIST))) ) )
Joey Armstrong36592e32022-11-28 09:00:28 -050025
26##--------------------##
27##---] INCLUDES [---##
28##--------------------##
Joey Armstrong0cbee512023-10-18 15:39:24 -040029include $(TOP)/makefiles/include.mk # top level include
Zack Williams071eda22019-05-15 18:19:51 -070030
31# You can set these variables from the command line.
32SPHINXOPTS ?=
33SPHINXBUILD ?= sphinx-build
34SOURCEDIR ?= .
35BUILDDIR ?= _build
36
Zack Williams88df4742019-12-20 08:24:47 -070037# Other repos with documentation to include.
38# edit the `git_refs` file with the commit/tag/branch that you want to use
Andrea Campanellac18d1182021-09-10 12:01:38 +020039OTHER_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 -070040
Joey Armstrong36592e32022-11-28 09:00:28 -050041ifdef NO_OTHER_REPO_DOCS
42 # Inhibit pulling in external repos.
43 # python 3.10+ patching not supported by all repos yet.
44 OTHER_REPO_DOCS := $(null)
45endif
46
Zack Williams16042b62020-03-29 22:03:16 -070047# Static docs, built by other means (usually robot framework)
48STATIC_DOCS := _static/voltha-system-tests _static/cord-tester
49
Joey Armstrong4de98b72023-02-09 14:51:38 -050050# Why is existing source Makefile PHONY (?)
Zack Williams88df4742019-12-20 08:24:47 -070051.PHONY: help test lint reload Makefile prep
Zack Williams071eda22019-05-15 18:19:51 -070052
Joey Armstrong4de98b72023-02-09 14:51:38 -050053## -----------------------------------------------------------------------
Joey Armstrong721519c2023-11-13 15:30:54 -050054## Intent: Display makefile target help
55## -----------------------------------------------------------------------
56help :: help-targets-main
57help-verbose :: help-targets-sphinx
58
59## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -050060## Intent: Real time viewing, dynamically generate and reload document
61## changes for web browser viewing.
62## Usage:
63## make reload
64## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -040065reload: $(venv-activate-patched)
Joey Armstrong4de98b72023-02-09 14:51:38 -050066 $(activate) && sphinx-reload $(SOURCEDIR)
Zack Williams071eda22019-05-15 18:19:51 -070067
Joey Armstrong8d62cd92022-12-22 13:53:48 -050068## -----------------------------------------------------------------------
69## Intent: lint and link verification. linkcheck is part of sphinx
Joey Armstrong64b82492023-06-01 17:34:39 -040070## See Also: make test-errors
Joey Armstrong8d62cd92022-12-22 13:53:48 -050071## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070072test: lint linkcheck
Joey Armstronga8bc8e12022-12-04 07:06:59 -050073
Joey Armstrong50895b82023-09-14 16:44:28 -040074# [TODO] relocate into repo:onf-make/
75lint : $(venv-activate-patched)
76linkcheck : $(venv-activate-patched)
77
Joey Armstrong8d62cd92022-12-22 13:53:48 -050078## -----------------------------------------------------------------------
79## Intent: Exercise all generation targets
Joey Armstrong4de98b72023-02-09 14:51:38 -050080## Bridge: library workaround to support legacy targets
Joey Armstrong8d62cd92022-12-22 13:53:48 -050081## -----------------------------------------------------------------------
82test-all-targets += html
83test-all-targets += coverage
84# test-all-targets += changes
85# test-all-targets += info
86test-all-targets += man
87test-all-targe4ts += text
88# test-all-targets += latex
89
Joey Armstrong8d62cd92022-12-22 13:53:48 -050090test-all : test
91 $(MAKE) $(test-all-targets)
92
Joey Armstrong36592e32022-11-28 09:00:28 -050093# doctest
94# coverage
95# linkcheck
Zack Williams071eda22019-05-15 18:19:51 -070096
Joey Armstrong0cbee512023-10-18 15:39:24 -040097# -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070098# currently not enabled, should be added to lint target
Joey Armstrong0cbee512023-10-18 15:39:24 -040099# [TODO] Create repo:onf-make/makefiles/lint/mdl
100# -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700101LINT_STYLE ?= mdl_strict.rb
102md-lint: | $(OTHER_REPO_DOCS)
103 @echo "markdownlint(mdl) version: `mdl --version`"
104 @echo "style config:"
105 @echo "---"
106 @cat $(LINT_STYLE)
107 @echo "---"
Joey Armstrong4de98b72023-02-09 14:51:38 -0500108 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 -0700109
110# clean up
Joey Armstrong64b82492023-06-01 17:34:39 -0400111clean ::
Joey Armstrong36592e32022-11-28 09:00:28 -0500112 $(RM) -r $(BUILDDIR) $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Zack Williams071eda22019-05-15 18:19:51 -0700113
Joey Armstrong4de98b72023-02-09 14:51:38 -0500114clean-all sterile :: clean
115 $(RM) -r $(venv-activate-script) repos
Zack Williams071eda22019-05-15 18:19:51 -0700116
Zack Williams071eda22019-05-15 18:19:51 -0700117# checkout the repos inside repos/ dir
118repos:
119 mkdir repos
120
121# build directory paths in repos/* to perform 'git clone <repo>' into
122CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
123
124# Host holding the git server
125REPO_HOST ?= https://gerrit.opencord.org
126
127# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
128# pre-populate it under repos/ with the specific commit to being validated
129SKIP_CHECKOUT ?=
130
Zack Williams88df4742019-12-20 08:24:47 -0700131# clone (only if doesn't exist)
Zack Williams071eda22019-05-15 18:19:51 -0700132$(CHECKOUT_REPOS): | repos
Zack Williams071eda22019-05-15 18:19:51 -0700133 if [ ! -d '$@' ] ;\
134 then git clone $(REPO_HOST)/$(@F) $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700135 fi
136
Joey Armstrong4de98b72023-02-09 14:51:38 -0500137## -----------------------------------------------------------------------
138## Intent: checkout correct ref if not under test, then copy
139## subdirectories into main docs dir
140## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700141$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
Zack Williams88df4742019-12-20 08:24:47 -0700142 if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
143 then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700144 cd "repos/$@" && git checkout $$GIT_REF ;\
Zack Williams88df4742019-12-20 08:24:47 -0700145 fi
Zack Williams17e34022019-12-20 13:51:54 -0700146 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
Zack Williams33085522020-02-28 11:41:01 -0700147 cp -r repos/$(@)$$GIT_SUBDIR $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700148
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100149# Build Robot documentation in voltha-system-tests and copy it into _static.
150_static/voltha-system-tests: | $(OTHER_REPO_DOCS)
151 make -C voltha-system-tests gendocs
152 mkdir -p $@
153 cp -r voltha-system-tests/gendocs/* $@
154
Andy Bavier39d67b12020-02-27 16:08:52 -0700155# Build Robot documentation in cord-tester and copy it into _static.
156_static/cord-tester: | $(OTHER_REPO_DOCS)
157 make -C cord-tester gendocs
158 mkdir -p $@
159 cp -r cord-tester/gendocs/* $@
160
Joey Armstrong4de98b72023-02-09 14:51:38 -0500161## -----------------------------------------------------------------------
162## Intent: generate a list of git checksums suitable for updating git_refs
163## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700164freeze: repos
165 @for repo in $(OTHER_REPO_DOCS) ; do \
166 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700167 cd "repos/$$repo" > /dev/null ;\
Zack Williams071eda22019-05-15 18:19:51 -0700168 HEAD_SHA=`git rev-parse HEAD` ;\
169 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700170 cd ../.. ;\
Zack Williams071eda22019-05-15 18:19:51 -0700171 done
172
Joey Armstrong4de98b72023-02-09 14:51:38 -0500173## -----------------------------------------------------------------------
174## Intent: build multiple versions
175## -----------------------------------------------------------------------
Joey Armstrong7be65812023-09-29 18:35:31 -0400176multiversion: $(venv-activate-patched) Makefile | prep $(OTHER_REPO_DOCS)
Joey Armstrong4de98b72023-02-09 14:51:38 -0500177 $(activate)\
178 && sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
Zack Williams16042b62020-03-29 22:03:16 -0700179 cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
Zack Williams88df4742019-12-20 08:24:47 -0700180
Joey Armstrong4de98b72023-02-09 14:51:38 -0500181## -----------------------------------------------------------------------
182## Intent: used in sphinx-multiversion to properly link
183## -----------------------------------------------------------------------
Zack Williams16042b62020-03-29 22:03:16 -0700184prep: | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Andy Bavier5dee6ae2020-01-29 16:03:40 -0700185
Joey Armstrong4de98b72023-02-09 14:51:38 -0500186## -----------------------------------------------------------------------
187## Intent: Forward sphinx supported targets to sphinxbuild.
188## Bridge: legacy makefile wildcard rule forwarded unknown targets to sphinx.
189## library makefiles do more so transfer control only when needed.
190## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -0400191include $(ONF_MAKEDIR)/voltha/docs-catchall-targets.mk
Joey Armstrong7be65812023-09-29 18:35:31 -0400192voltha-docs-catchall : $(voltha-docs-catchall)
193$(voltha-docs-catchall): $(venv-activate-patched) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Joey Armstrong36592e32022-11-28 09:00:28 -0500194 @echo " ** CATCHALL: $@"
Joey Armstrong4de98b72023-02-09 14:51:38 -0500195 $(activate)\
196 && $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Joey Armstrong36592e32022-11-28 09:00:28 -0500197
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500198## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500199## Intent: Display makefile target help
200## -----------------------------------------------------------------------
Joey Armstrong721519c2023-11-13 15:30:54 -0500201help-targets-sphinx : $(venv-activate-patched)
Joey Armstrong4de98b72023-02-09 14:51:38 -0500202 @ echo
Joey Armstrong721519c2023-11-13 15:30:54 -0500203 @echo '[HELP: Sphinx]'
Joey Armstrong4de98b72023-02-09 14:51:38 -0500204 $(HIDE)$(activate) \
205 && $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
206
207## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400208## Intent: Display WARNINGS buried in sphinx output
209## -----------------------------------------------------------------------
210warnings-log := warnings.log
Joey Armstrong4f93b762023-06-06 08:36:02 -0400211warnings: sterile
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400212 $(MAKE) html 2>&1 \
213 | sed -e 's@\([Ww][Aa][Rr][Nn][Ii][Nn][Gg]\)@\n\1@g' \
214 > "$(warnings-log)"
Joey Armstrong4f93b762023-06-06 08:36:02 -0400215 grep 'WARNING' $(warnings-log)
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400216
Joey Armstrong4f93b762023-06-06 08:36:02 -0400217## -----------------------------------------------------------------------
218## Intent: Summarize linkcheck failures
219## -----------------------------------------------------------------------
220.PHONY: broken-log
221broken-log := broken.log
222broken-log : sterile
223 $(MAKE) linkcheck 2>&1 | tee "$(broken-log)"
224 ! grep broken "$(broken-log)"
225 grep -i error _build/linkcheck/output.txt
226
227## -----------------------------------------------------------------------
228## Intent:
229## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400230clean::
Joey Armstrong4f93b762023-06-06 08:36:02 -0400231 $(RM) $(broken-log)
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400232 $(RM) $(warnings-log)
233
Joey Armstrong4f93b762023-06-06 08:36:02 -0400234## -----------------------------------------------------------------------
235## Intent:
236## -----------------------------------------------------------------------
Joey Armstrong721519c2023-11-13 15:30:54 -0500237help :: help-targets-main
238help-targets-main :
239
240 @echo
241 @echo '[HELP]'
242 @printf ' %-30.30s %s\n' 'help' \
243 'Summary makefile target help'
244 @printf ' %-30.30s %s\n' 'help-verbose' \
245 'Extended makefile target help'
246
247 @echo
248 @echo '[INIT]'
249 @printf ' %-30.30s %s\n' 'init' \
250 'Alias for git-submodules'
251 @printf ' %-30.30s %s\n' 'git-submodules' \
252 'Checkout external dependent repositories'
253
254 @echo
255 @echo '[TEST: Failures]'
256 @printf ' %-30.30s %s\n' 'broken' \
257 'Display broken URLs detected in linkcheck output'
258 @printf ' %-30.30s %s\n' 'warnings' \
259 'Display WARNING strings buried in sphinx output'
260
261## -----------------------------------------------------------------------
262## Intent: Checkout external repository dependencies
263## -----------------------------------------------------------------------
264init :: git-submodules
265
266git-submodules:
267 git submodule update --init --recursive
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400268
269## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500270## Intent: Display make hel footer
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500271## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -0400272include $(ONF_MAKEDIR)/help/trailer.mk
Joey Armstrong36592e32022-11-28 09:00:28 -0500273
274# [EOF]