blob: 3de80c0a18ca8cb85832749cd2a99e01f4c650b2 [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
21TOP ?= .
22MAKEDIR ?= $(TOP)/makefiles
23
24$(if $(VERBOSE),$(eval export VERBOSE=$(VERBOSE))) # visible to include(s)
25
26##--------------------##
27##---] INCLUDES [---##
28##--------------------##
Joey Armstrong4de98b72023-02-09 14:51:38 -050029-include config.mk
30include $(MAKEDIR)/include.mk
Zack Williams071eda22019-05-15 18:19:51 -070031
32# You can set these variables from the command line.
33SPHINXOPTS ?=
34SPHINXBUILD ?= sphinx-build
35SOURCEDIR ?= .
36BUILDDIR ?= _build
37
Zack Williams88df4742019-12-20 08:24:47 -070038# Other repos with documentation to include.
39# edit the `git_refs` file with the commit/tag/branch that you want to use
Andrea Campanellac18d1182021-09-10 12:01:38 +020040OTHER_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 -070041
Joey Armstrong36592e32022-11-28 09:00:28 -050042ifdef NO_OTHER_REPO_DOCS
43 # Inhibit pulling in external repos.
44 # python 3.10+ patching not supported by all repos yet.
45 OTHER_REPO_DOCS := $(null)
46endif
47
Zack Williams16042b62020-03-29 22:03:16 -070048# Static docs, built by other means (usually robot framework)
49STATIC_DOCS := _static/voltha-system-tests _static/cord-tester
50
Joey Armstrong4de98b72023-02-09 14:51:38 -050051# Why is existing source Makefile PHONY (?)
Zack Williams88df4742019-12-20 08:24:47 -070052.PHONY: help test lint reload Makefile prep
Zack Williams071eda22019-05-15 18:19:51 -070053
Joey Armstrong4de98b72023-02-09 14:51:38 -050054## -----------------------------------------------------------------------
55## Intent: Real time viewing, dynamically generate and reload document
56## changes for web browser viewing.
57## Usage:
58## make reload
59## -----------------------------------------------------------------------
60reload: $(venv-activate-script)
61 $(activate) && sphinx-reload $(SOURCEDIR)
Zack Williams071eda22019-05-15 18:19:51 -070062
Joey Armstrong8d62cd92022-12-22 13:53:48 -050063## -----------------------------------------------------------------------
64## Intent: lint and link verification. linkcheck is part of sphinx
Joey Armstrong64b82492023-06-01 17:34:39 -040065## See Also: make test-errors
Joey Armstrong8d62cd92022-12-22 13:53:48 -050066## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070067test: lint linkcheck
Joey Armstronga8bc8e12022-12-04 07:06:59 -050068
Joey Armstrong8d62cd92022-12-22 13:53:48 -050069## -----------------------------------------------------------------------
70## Intent: Exercise all generation targets
Joey Armstrong4de98b72023-02-09 14:51:38 -050071## Bridge: library workaround to support legacy targets
Joey Armstrong8d62cd92022-12-22 13:53:48 -050072## -----------------------------------------------------------------------
73test-all-targets += html
74test-all-targets += coverage
75# test-all-targets += changes
76# test-all-targets += info
77test-all-targets += man
78test-all-targe4ts += text
79# test-all-targets += latex
80
Joey Armstrong8d62cd92022-12-22 13:53:48 -050081test-all : test
82 $(MAKE) $(test-all-targets)
83
Joey Armstrong36592e32022-11-28 09:00:28 -050084# doctest
85# coverage
86# linkcheck
Zack Williams071eda22019-05-15 18:19:51 -070087
Zack Williams071eda22019-05-15 18:19:51 -070088# currently not enabled, should be added to lint target
89LINT_STYLE ?= mdl_strict.rb
90md-lint: | $(OTHER_REPO_DOCS)
91 @echo "markdownlint(mdl) version: `mdl --version`"
92 @echo "style config:"
93 @echo "---"
94 @cat $(LINT_STYLE)
95 @echo "---"
Joey Armstrong4de98b72023-02-09 14:51:38 -050096 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 -070097
98# clean up
Joey Armstrong64b82492023-06-01 17:34:39 -040099clean ::
Joey Armstrong36592e32022-11-28 09:00:28 -0500100 $(RM) -r $(BUILDDIR) $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Zack Williams071eda22019-05-15 18:19:51 -0700101
Joey Armstrong4de98b72023-02-09 14:51:38 -0500102clean-all sterile :: clean
103 $(RM) -r $(venv-activate-script) repos
Zack Williams071eda22019-05-15 18:19:51 -0700104
Zack Williams071eda22019-05-15 18:19:51 -0700105# checkout the repos inside repos/ dir
106repos:
107 mkdir repos
108
109# build directory paths in repos/* to perform 'git clone <repo>' into
110CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
111
112# Host holding the git server
113REPO_HOST ?= https://gerrit.opencord.org
114
115# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
116# pre-populate it under repos/ with the specific commit to being validated
117SKIP_CHECKOUT ?=
118
Zack Williams88df4742019-12-20 08:24:47 -0700119# clone (only if doesn't exist)
Zack Williams071eda22019-05-15 18:19:51 -0700120$(CHECKOUT_REPOS): | repos
Zack Williams071eda22019-05-15 18:19:51 -0700121 if [ ! -d '$@' ] ;\
122 then git clone $(REPO_HOST)/$(@F) $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700123 fi
124
Joey Armstrong4de98b72023-02-09 14:51:38 -0500125## -----------------------------------------------------------------------
126## Intent: checkout correct ref if not under test, then copy
127## subdirectories into main docs dir
128## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700129$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
Zack Williams88df4742019-12-20 08:24:47 -0700130 if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
131 then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700132 cd "repos/$@" && git checkout $$GIT_REF ;\
Zack Williams88df4742019-12-20 08:24:47 -0700133 fi
Zack Williams17e34022019-12-20 13:51:54 -0700134 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
Zack Williams33085522020-02-28 11:41:01 -0700135 cp -r repos/$(@)$$GIT_SUBDIR $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700136
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100137# Build Robot documentation in voltha-system-tests and copy it into _static.
138_static/voltha-system-tests: | $(OTHER_REPO_DOCS)
139 make -C voltha-system-tests gendocs
140 mkdir -p $@
141 cp -r voltha-system-tests/gendocs/* $@
142
Andy Bavier39d67b12020-02-27 16:08:52 -0700143# Build Robot documentation in cord-tester and copy it into _static.
144_static/cord-tester: | $(OTHER_REPO_DOCS)
145 make -C cord-tester gendocs
146 mkdir -p $@
147 cp -r cord-tester/gendocs/* $@
148
Joey Armstrong4de98b72023-02-09 14:51:38 -0500149## -----------------------------------------------------------------------
150## Intent: generate a list of git checksums suitable for updating git_refs
151## -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -0700152freeze: repos
153 @for repo in $(OTHER_REPO_DOCS) ; do \
154 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700155 cd "repos/$$repo" > /dev/null ;\
Zack Williams071eda22019-05-15 18:19:51 -0700156 HEAD_SHA=`git rev-parse HEAD` ;\
157 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700158 cd ../.. ;\
Zack Williams071eda22019-05-15 18:19:51 -0700159 done
160
Joey Armstrong4de98b72023-02-09 14:51:38 -0500161## -----------------------------------------------------------------------
162## Intent: build multiple versions
163## -----------------------------------------------------------------------
164multiversion: $(venv-activate-script) Makefile | prep $(OTHER_REPO_DOCS)
165 $(activate)\
166 && sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
Zack Williams16042b62020-03-29 22:03:16 -0700167 cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
Zack Williams88df4742019-12-20 08:24:47 -0700168
Joey Armstrong4de98b72023-02-09 14:51:38 -0500169## -----------------------------------------------------------------------
170## Intent: used in sphinx-multiversion to properly link
171## -----------------------------------------------------------------------
Zack Williams16042b62020-03-29 22:03:16 -0700172prep: | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Andy Bavier5dee6ae2020-01-29 16:03:40 -0700173
Joey Armstrong4de98b72023-02-09 14:51:38 -0500174## -----------------------------------------------------------------------
175## Intent: Forward sphinx supported targets to sphinxbuild.
176## Bridge: legacy makefile wildcard rule forwarded unknown targets to sphinx.
177## library makefiles do more so transfer control only when needed.
178## -----------------------------------------------------------------------
Joey Armstrong1a9b7d12022-12-19 14:13:07 -0500179include $(MAKEDIR)/voltha/docs-catchall-targets.mk
Joey Armstrong4de98b72023-02-09 14:51:38 -0500180$(voltha-docs-catchall): $(venv-activate-script) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Joey Armstrong36592e32022-11-28 09:00:28 -0500181 @echo " ** CATCHALL: $@"
Joey Armstrong4de98b72023-02-09 14:51:38 -0500182 $(activate)\
183 && $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Joey Armstrong36592e32022-11-28 09:00:28 -0500184
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500185## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500186## Intent: Display makefile target help
187## -----------------------------------------------------------------------
188help :: $(venv-activate-script)
189 @ echo
190 $(HIDE)$(activate) \
191 && $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
192
193## -----------------------------------------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400194## Intent: Display WARNINGS buried in sphinx output
195## -----------------------------------------------------------------------
196warnings-log := warnings.log
197warnings:
198 $(MAKE) html 2>&1 \
199 | sed -e 's@\([Ww][Aa][Rr][Nn][Ii][Nn][Gg]\)@\n\1@g' \
200 > "$(warnings-log)"
201 less --ignore-case --hilite-search --pattern='/warning' $(warnings-log)
202
203clean::
204 $(RM) $(warnings-log)
205
206help ::
207 @echo " warnings Display WARNING strings buried in sphinx output"
208
209## -----------------------------------------------------------------------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500210## Intent: Display make hel footer
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500211## -----------------------------------------------------------------------
Joey Armstrong36592e32022-11-28 09:00:28 -0500212include $(MAKEDIR)/help/trailer.mk
213
214# [EOF]