blob: 5a307f73259f105433a3b20a202a1ac1d7a1e8d6 [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##-------------------##
24TOP ?=$(strip \
25 $(dir \
26 $(abspath $(lastword $(MAKEFILE_LIST)))\
27 )\
28)
Joey Armstrong36592e32022-11-28 09:00:28 -050029
30##--------------------##
31##---] INCLUDES [---##
32##--------------------##
Joey Armstrong449ce7a2023-07-18 18:32:24 -040033include $(TOP)/config.mk# # configure
34include $(TOP)/makefiles/include.mk # top level include
Zack Williams071eda22019-05-15 18:19:51 -070035
36# You can set these variables from the command line.
37SPHINXOPTS ?=
38SPHINXBUILD ?= sphinx-build
39SOURCEDIR ?= .
40BUILDDIR ?= _build
41
Zack Williams88df4742019-12-20 08:24:47 -070042# Other repos with documentation to include.
43# edit the `git_refs` file with the commit/tag/branch that you want to use
Andrea Campanellac18d1182021-09-10 12:01:38 +020044OTHER_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 -070045
Joey Armstrong36592e32022-11-28 09:00:28 -050046ifdef NO_OTHER_REPO_DOCS
47 # Inhibit pulling in external repos.
48 # python 3.10+ patching not supported by all repos yet.
49 OTHER_REPO_DOCS := $(null)
50endif
51
Zack Williams16042b62020-03-29 22:03:16 -070052# Static docs, built by other means (usually robot framework)
53STATIC_DOCS := _static/voltha-system-tests _static/cord-tester
54
Joey Armstrong4de98b72023-02-09 14:51:38 -050055# Why is existing source Makefile PHONY (?)
Zack Williams88df4742019-12-20 08:24:47 -070056.PHONY: help test lint reload Makefile prep
Zack Williams071eda22019-05-15 18:19:51 -070057
Joey Armstrong4de98b72023-02-09 14:51:38 -050058## -----------------------------------------------------------------------
59## Intent: Real time viewing, dynamically generate and reload document
60## changes for web browser viewing.
61## Usage:
62## make reload
63## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -040064reload: $(venv-activate-patched)
Joey Armstrong4de98b72023-02-09 14:51:38 -050065 $(activate) && sphinx-reload $(SOURCEDIR)
Zack Williams071eda22019-05-15 18:19:51 -070066
Joey Armstrong8d62cd92022-12-22 13:53:48 -050067## -----------------------------------------------------------------------
68## Intent: lint and link verification. linkcheck is part of sphinx
Joey Armstrong64b82492023-06-01 17:34:39 -040069## See Also: make test-errors
Joey Armstrong8d62cd92022-12-22 13:53:48 -050070## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070071test: lint linkcheck
Joey Armstronga8bc8e12022-12-04 07:06:59 -050072
Joey Armstrong8d62cd92022-12-22 13:53:48 -050073## -----------------------------------------------------------------------
74## Intent: Exercise all generation targets
Joey Armstrong4de98b72023-02-09 14:51:38 -050075## Bridge: library workaround to support legacy targets
Joey Armstrong8d62cd92022-12-22 13:53:48 -050076## -----------------------------------------------------------------------
77test-all-targets += html
78test-all-targets += coverage
79# test-all-targets += changes
80# test-all-targets += info
81test-all-targets += man
82test-all-targe4ts += text
83# test-all-targets += latex
84
Joey Armstrong8d62cd92022-12-22 13:53:48 -050085test-all : test
86 $(MAKE) $(test-all-targets)
87
Joey Armstrong36592e32022-11-28 09:00:28 -050088# doctest
89# coverage
90# linkcheck
Zack Williams071eda22019-05-15 18:19:51 -070091
Zack Williams071eda22019-05-15 18:19:51 -070092# currently not enabled, should be added to lint target
93LINT_STYLE ?= mdl_strict.rb
94md-lint: | $(OTHER_REPO_DOCS)
95 @echo "markdownlint(mdl) version: `mdl --version`"
96 @echo "style config:"
97 @echo "---"
98 @cat $(LINT_STYLE)
99 @echo "---"
Joey Armstrong4de98b72023-02-09 14:51:38 -0500100 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 -0700101
102# clean up
Joey Armstrong64b82492023-06-01 17:34:39 -0400103clean ::
Joey Armstrong36592e32022-11-28 09:00:28 -0500104 $(RM) -r $(BUILDDIR) $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Zack Williams071eda22019-05-15 18:19:51 -0700105
Joey Armstrong4de98b72023-02-09 14:51:38 -0500106clean-all sterile :: clean
107 $(RM) -r $(venv-activate-script) repos
Zack Williams071eda22019-05-15 18:19:51 -0700108
Zack Williams071eda22019-05-15 18:19:51 -0700109# checkout the repos inside repos/ dir
110repos:
111 mkdir repos
112
113# build directory paths in repos/* to perform 'git clone <repo>' into
114CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
115
116# Host holding the git server
117REPO_HOST ?= https://gerrit.opencord.org
118
119# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
120# pre-populate it under repos/ with the specific commit to being validated
121SKIP_CHECKOUT ?=
122
Zack Williams88df4742019-12-20 08:24:47 -0700123# clone (only if doesn't exist)
Zack Williams071eda22019-05-15 18:19:51 -0700124$(CHECKOUT_REPOS): | repos
Zack Williams071eda22019-05-15 18:19:51 -0700125 if [ ! -d '$@' ] ;\
126 then git clone $(REPO_HOST)/$(@F) $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700127 fi
128
Joey Armstrong4de98b72023-02-09 14:51:38 -0500129## -----------------------------------------------------------------------
130## Intent: checkout correct ref if not under test, then copy
131## subdirectories into main docs dir
132## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700133$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
Zack Williams88df4742019-12-20 08:24:47 -0700134 if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
135 then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700136 cd "repos/$@" && git checkout $$GIT_REF ;\
Zack Williams88df4742019-12-20 08:24:47 -0700137 fi
Zack Williams17e34022019-12-20 13:51:54 -0700138 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
Zack Williams33085522020-02-28 11:41:01 -0700139 cp -r repos/$(@)$$GIT_SUBDIR $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700140
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100141# Build Robot documentation in voltha-system-tests and copy it into _static.
142_static/voltha-system-tests: | $(OTHER_REPO_DOCS)
143 make -C voltha-system-tests gendocs
144 mkdir -p $@
145 cp -r voltha-system-tests/gendocs/* $@
146
Andy Bavier39d67b12020-02-27 16:08:52 -0700147# Build Robot documentation in cord-tester and copy it into _static.
148_static/cord-tester: | $(OTHER_REPO_DOCS)
149 make -C cord-tester gendocs
150 mkdir -p $@
151 cp -r cord-tester/gendocs/* $@
152
Joey Armstrong4de98b72023-02-09 14:51:38 -0500153## -----------------------------------------------------------------------
154## Intent: generate a list of git checksums suitable for updating git_refs
155## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700156freeze: repos
157 @for repo in $(OTHER_REPO_DOCS) ; do \
158 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700159 cd "repos/$$repo" > /dev/null ;\
Zack Williams071eda22019-05-15 18:19:51 -0700160 HEAD_SHA=`git rev-parse HEAD` ;\
161 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700162 cd ../.. ;\
Zack Williams071eda22019-05-15 18:19:51 -0700163 done
164
Joey Armstrong4de98b72023-02-09 14:51:38 -0500165## -----------------------------------------------------------------------
166## Intent: build multiple versions
167## -----------------------------------------------------------------------
168multiversion: $(venv-activate-script) Makefile | prep $(OTHER_REPO_DOCS)
169 $(activate)\
170 && sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
Zack Williams16042b62020-03-29 22:03:16 -0700171 cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
Zack Williams88df4742019-12-20 08:24:47 -0700172
Joey Armstrong4de98b72023-02-09 14:51:38 -0500173## -----------------------------------------------------------------------
174## Intent: used in sphinx-multiversion to properly link
175## -----------------------------------------------------------------------
Zack Williams16042b62020-03-29 22:03:16 -0700176prep: | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Andy Bavier5dee6ae2020-01-29 16:03:40 -0700177
Joey Armstrong4de98b72023-02-09 14:51:38 -0500178## -----------------------------------------------------------------------
179## Intent: Forward sphinx supported targets to sphinxbuild.
180## Bridge: legacy makefile wildcard rule forwarded unknown targets to sphinx.
181## library makefiles do more so transfer control only when needed.
182## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -0400183include $(ONF_MAKEDIR)/voltha/docs-catchall-targets.mk
Joey Armstrong4de98b72023-02-09 14:51:38 -0500184$(voltha-docs-catchall): $(venv-activate-script) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Joey Armstrong36592e32022-11-28 09:00:28 -0500185 @echo " ** CATCHALL: $@"
Joey Armstrong4de98b72023-02-09 14:51:38 -0500186 $(activate)\
187 && $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Joey Armstrong36592e32022-11-28 09:00:28 -0500188
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500189## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500190## Intent: Display makefile target help
191## -----------------------------------------------------------------------
192help :: $(venv-activate-script)
193 @ echo
194 $(HIDE)$(activate) \
195 && $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
196
197## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400198## Intent: Display WARNINGS buried in sphinx output
199## -----------------------------------------------------------------------
200warnings-log := warnings.log
Joey Armstrong4f93b762023-06-06 08:36:02 -0400201warnings: sterile
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400202 $(MAKE) html 2>&1 \
203 | sed -e 's@\([Ww][Aa][Rr][Nn][Ii][Nn][Gg]\)@\n\1@g' \
204 > "$(warnings-log)"
Joey Armstrong4f93b762023-06-06 08:36:02 -0400205 grep 'WARNING' $(warnings-log)
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400206
Joey Armstrong4f93b762023-06-06 08:36:02 -0400207## -----------------------------------------------------------------------
208## Intent: Summarize linkcheck failures
209## -----------------------------------------------------------------------
210.PHONY: broken-log
211broken-log := broken.log
212broken-log : sterile
213 $(MAKE) linkcheck 2>&1 | tee "$(broken-log)"
214 ! grep broken "$(broken-log)"
215 grep -i error _build/linkcheck/output.txt
216
217## -----------------------------------------------------------------------
218## Intent:
219## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400220clean::
Joey Armstrong4f93b762023-06-06 08:36:02 -0400221 $(RM) $(broken-log)
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400222 $(RM) $(warnings-log)
223
Joey Armstrong4f93b762023-06-06 08:36:02 -0400224## -----------------------------------------------------------------------
225## Intent:
226## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400227help ::
228 @echo " warnings Display WARNING strings buried in sphinx output"
229
230## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500231## Intent: Display make hel footer
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500232## -----------------------------------------------------------------------
Joey Armstrong449ce7a2023-07-18 18:32:24 -0400233include $(ONF_MAKEDIR)/help/trailer.mk
Joey Armstrong36592e32022-11-28 09:00:28 -0500234
235# [EOF]