blob: f99c80988c36df4b5667f7d5853cf880b597aa7d [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## -----------------------------------------------------------------------
54## Intent: Real time viewing, dynamically generate and reload document
55## changes for web browser viewing.
56## Usage:
57## make reload
58## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -040059reload: $(venv-activate-patched)
Joey Armstrong4de98b72023-02-09 14:51:38 -050060 $(activate) && sphinx-reload $(SOURCEDIR)
Zack Williams071eda22019-05-15 18:19:51 -070061
Joey Armstrong8d62cd92022-12-22 13:53:48 -050062## -----------------------------------------------------------------------
63## Intent: lint and link verification. linkcheck is part of sphinx
Joey Armstrong64b82492023-06-01 17:34:39 -040064## See Also: make test-errors
Joey Armstrong8d62cd92022-12-22 13:53:48 -050065## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070066test: lint linkcheck
Joey Armstronga8bc8e12022-12-04 07:06:59 -050067
Joey Armstrong50895b82023-09-14 16:44:28 -040068# [TODO] relocate into repo:onf-make/
69lint : $(venv-activate-patched)
70linkcheck : $(venv-activate-patched)
71
Joey Armstrong8d62cd92022-12-22 13:53:48 -050072## -----------------------------------------------------------------------
73## Intent: Exercise all generation targets
Joey Armstrong4de98b72023-02-09 14:51:38 -050074## Bridge: library workaround to support legacy targets
Joey Armstrong8d62cd92022-12-22 13:53:48 -050075## -----------------------------------------------------------------------
76test-all-targets += html
77test-all-targets += coverage
78# test-all-targets += changes
79# test-all-targets += info
80test-all-targets += man
81test-all-targe4ts += text
82# test-all-targets += latex
83
Joey Armstrong8d62cd92022-12-22 13:53:48 -050084test-all : test
85 $(MAKE) $(test-all-targets)
86
Joey Armstrong36592e32022-11-28 09:00:28 -050087# doctest
88# coverage
89# linkcheck
Zack Williams071eda22019-05-15 18:19:51 -070090
Joey Armstrong0cbee512023-10-18 15:39:24 -040091# -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070092# currently not enabled, should be added to lint target
Joey Armstrong0cbee512023-10-18 15:39:24 -040093# [TODO] Create repo:onf-make/makefiles/lint/mdl
94# -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070095LINT_STYLE ?= mdl_strict.rb
96md-lint: | $(OTHER_REPO_DOCS)
97 @echo "markdownlint(mdl) version: `mdl --version`"
98 @echo "style config:"
99 @echo "---"
100 @cat $(LINT_STYLE)
101 @echo "---"
Joey Armstrong4de98b72023-02-09 14:51:38 -0500102 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 -0700103
104# clean up
Joey Armstrong64b82492023-06-01 17:34:39 -0400105clean ::
Joey Armstrong36592e32022-11-28 09:00:28 -0500106 $(RM) -r $(BUILDDIR) $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Zack Williams071eda22019-05-15 18:19:51 -0700107
Joey Armstrong4de98b72023-02-09 14:51:38 -0500108clean-all sterile :: clean
109 $(RM) -r $(venv-activate-script) repos
Zack Williams071eda22019-05-15 18:19:51 -0700110
Zack Williams071eda22019-05-15 18:19:51 -0700111# checkout the repos inside repos/ dir
112repos:
113 mkdir repos
114
115# build directory paths in repos/* to perform 'git clone <repo>' into
116CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
117
118# Host holding the git server
119REPO_HOST ?= https://gerrit.opencord.org
120
121# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
122# pre-populate it under repos/ with the specific commit to being validated
123SKIP_CHECKOUT ?=
124
Zack Williams88df4742019-12-20 08:24:47 -0700125# clone (only if doesn't exist)
Zack Williams071eda22019-05-15 18:19:51 -0700126$(CHECKOUT_REPOS): | repos
Zack Williams071eda22019-05-15 18:19:51 -0700127 if [ ! -d '$@' ] ;\
128 then git clone $(REPO_HOST)/$(@F) $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700129 fi
130
Joey Armstrong4de98b72023-02-09 14:51:38 -0500131## -----------------------------------------------------------------------
132## Intent: checkout correct ref if not under test, then copy
133## subdirectories into main docs dir
134## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700135$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
Zack Williams88df4742019-12-20 08:24:47 -0700136 if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
137 then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700138 cd "repos/$@" && git checkout $$GIT_REF ;\
Zack Williams88df4742019-12-20 08:24:47 -0700139 fi
Zack Williams17e34022019-12-20 13:51:54 -0700140 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
Zack Williams33085522020-02-28 11:41:01 -0700141 cp -r repos/$(@)$$GIT_SUBDIR $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700142
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100143# Build Robot documentation in voltha-system-tests and copy it into _static.
144_static/voltha-system-tests: | $(OTHER_REPO_DOCS)
145 make -C voltha-system-tests gendocs
146 mkdir -p $@
147 cp -r voltha-system-tests/gendocs/* $@
148
Andy Bavier39d67b12020-02-27 16:08:52 -0700149# Build Robot documentation in cord-tester and copy it into _static.
150_static/cord-tester: | $(OTHER_REPO_DOCS)
151 make -C cord-tester gendocs
152 mkdir -p $@
153 cp -r cord-tester/gendocs/* $@
154
Joey Armstrong4de98b72023-02-09 14:51:38 -0500155## -----------------------------------------------------------------------
156## Intent: generate a list of git checksums suitable for updating git_refs
157## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700158freeze: repos
159 @for repo in $(OTHER_REPO_DOCS) ; do \
160 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700161 cd "repos/$$repo" > /dev/null ;\
Zack Williams071eda22019-05-15 18:19:51 -0700162 HEAD_SHA=`git rev-parse HEAD` ;\
163 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700164 cd ../.. ;\
Zack Williams071eda22019-05-15 18:19:51 -0700165 done
166
Joey Armstrong4de98b72023-02-09 14:51:38 -0500167## -----------------------------------------------------------------------
168## Intent: build multiple versions
169## -----------------------------------------------------------------------
170multiversion: $(venv-activate-script) Makefile | prep $(OTHER_REPO_DOCS)
171 $(activate)\
172 && sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
Zack Williams16042b62020-03-29 22:03:16 -0700173 cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
Zack Williams88df4742019-12-20 08:24:47 -0700174
Joey Armstrong4de98b72023-02-09 14:51:38 -0500175## -----------------------------------------------------------------------
176## Intent: used in sphinx-multiversion to properly link
177## -----------------------------------------------------------------------
Zack Williams16042b62020-03-29 22:03:16 -0700178prep: | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Andy Bavier5dee6ae2020-01-29 16:03:40 -0700179
Joey Armstrong4de98b72023-02-09 14:51:38 -0500180## -----------------------------------------------------------------------
181## Intent: Forward sphinx supported targets to sphinxbuild.
182## Bridge: legacy makefile wildcard rule forwarded unknown targets to sphinx.
183## library makefiles do more so transfer control only when needed.
184## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -0400185include $(ONF_MAKEDIR)/voltha/docs-catchall-targets.mk
Joey Armstrong4de98b72023-02-09 14:51:38 -0500186$(voltha-docs-catchall): $(venv-activate-script) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Joey Armstrong36592e32022-11-28 09:00:28 -0500187 @echo " ** CATCHALL: $@"
Joey Armstrong4de98b72023-02-09 14:51:38 -0500188 $(activate)\
189 && $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Joey Armstrong36592e32022-11-28 09:00:28 -0500190
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500191## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500192## Intent: Display makefile target help
193## -----------------------------------------------------------------------
194help :: $(venv-activate-script)
195 @ echo
196 $(HIDE)$(activate) \
197 && $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
198
199## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400200## Intent: Display WARNINGS buried in sphinx output
201## -----------------------------------------------------------------------
202warnings-log := warnings.log
Joey Armstrong4f93b762023-06-06 08:36:02 -0400203warnings: sterile
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400204 $(MAKE) html 2>&1 \
205 | sed -e 's@\([Ww][Aa][Rr][Nn][Ii][Nn][Gg]\)@\n\1@g' \
206 > "$(warnings-log)"
Joey Armstrong4f93b762023-06-06 08:36:02 -0400207 grep 'WARNING' $(warnings-log)
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400208
Joey Armstrong4f93b762023-06-06 08:36:02 -0400209## -----------------------------------------------------------------------
210## Intent: Summarize linkcheck failures
211## -----------------------------------------------------------------------
212.PHONY: broken-log
213broken-log := broken.log
214broken-log : sterile
215 $(MAKE) linkcheck 2>&1 | tee "$(broken-log)"
216 ! grep broken "$(broken-log)"
217 grep -i error _build/linkcheck/output.txt
218
219## -----------------------------------------------------------------------
220## Intent:
221## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400222clean::
Joey Armstrong4f93b762023-06-06 08:36:02 -0400223 $(RM) $(broken-log)
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400224 $(RM) $(warnings-log)
225
Joey Armstrong4f93b762023-06-06 08:36:02 -0400226## -----------------------------------------------------------------------
227## Intent:
228## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400229help ::
230 @echo " warnings Display WARNING strings buried in sphinx output"
231
232## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500233## Intent: Display make hel footer
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500234## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -0400235include $(ONF_MAKEDIR)/help/trailer.mk
Joey Armstrong36592e32022-11-28 09:00:28 -0500236
237# [EOF]