blob: 0787d605de7f94a37f81113d3f7de6923e58aa5a [file] [log] [blame]
Joey Armstrong36592e32022-11-28 09:00:28 -05001# -*- makefile -*-
2# -----------------------------------------------------------------------
Joey Armstrong1a9b7d12022-12-19 14:13:07 -05003# Copyright 2022-2023 Open Networking Foundation
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##--------------------##
29include $(MAKEDIR)/consts.mk
30include $(MAKEDIR)/help/include.mk
31include $(MAKEDIR)/patches/include.mk
32include $(MAKEDIR)/help/variables.mk
Zack Williams071eda22019-05-15 18:19:51 -070033
34# You can set these variables from the command line.
35SPHINXOPTS ?=
36SPHINXBUILD ?= sphinx-build
37SOURCEDIR ?= .
38BUILDDIR ?= _build
39
Zack Williams88df4742019-12-20 08:24:47 -070040# Other repos with documentation to include.
41# edit the `git_refs` file with the commit/tag/branch that you want to use
Andrea Campanellac18d1182021-09-10 12:01:38 +020042OTHER_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 -070043
Joey Armstrong36592e32022-11-28 09:00:28 -050044ifdef NO_OTHER_REPO_DOCS
45 # Inhibit pulling in external repos.
46 # python 3.10+ patching not supported by all repos yet.
47 OTHER_REPO_DOCS := $(null)
48endif
49
Zack Williams16042b62020-03-29 22:03:16 -070050# Static docs, built by other means (usually robot framework)
51STATIC_DOCS := _static/voltha-system-tests _static/cord-tester
52
53# name of python virtualenv that is used to run commands
54VENV_NAME := venv_docs
Zack Williams071eda22019-05-15 18:19:51 -070055
Zack Williams88df4742019-12-20 08:24:47 -070056.PHONY: help test lint reload Makefile prep
Zack Williams071eda22019-05-15 18:19:51 -070057
Zack Williams16042b62020-03-29 22:03:16 -070058# Put it first so that "make" without argument is like "make help".
Joey Armstrong36592e32022-11-28 09:00:28 -050059help :: $(VENV_NAME)
60 @ echo
61 @ source $</bin/activate ; set -u ;\
Zack Williams16042b62020-03-29 22:03:16 -070062 $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
63
Joey Armstrong36592e32022-11-28 09:00:28 -050064# -----------------------------------------------------------------------
Zack Williams071eda22019-05-15 18:19:51 -070065# Create the virtualenv with all the tools installed
Joey Armstrong36592e32022-11-28 09:00:28 -050066# -----------------------------------------------------------------------
Joey Armstrongf88b7382022-12-02 15:04:21 -050067.PHONY: venv
68venv: $(VENV_NAME)
69
Zack Williams16042b62020-03-29 22:03:16 -070070$(VENV_NAME):
Joey Armstrong36592e32022-11-28 09:00:28 -050071 @echo
72 @echo "============================="
73 @echo "Installing python virtual env"
74 @echo "============================="
75 virtualenv -p python3 $@ ;\
76 source ./$@/bin/activate ;\
77 python -m pip install -r requirements.txt
78ifndef NO_PATCH
79 @echo
80 @echo "========================================"
Joey Armstronga8bc8e12022-12-04 07:06:59 -050081 @echo "Applying python virtualenv patches as needed (v3.10+)"
Joey Armstrong36592e32022-11-28 09:00:28 -050082 @echo "========================================"
Joey Armstrong1a9b7d12022-12-19 14:13:07 -050083 ./patches/python_310_migration.sh '--venv' "$@" 'apply'
Joey Armstrong36592e32022-11-28 09:00:28 -050084endif
Zack Williams071eda22019-05-15 18:19:51 -070085
86# automatically reload changes in browser as they're made
Zack Williams16042b62020-03-29 22:03:16 -070087reload: $(VENV_NAME)
Zack Williamsc6460c22019-12-18 14:54:43 -070088 source $</bin/activate ; set -u ;\
Zack Williams071eda22019-05-15 18:19:51 -070089 sphinx-reload $(SOURCEDIR)
90
91# lint and link verification. linkcheck is part of sphinx
92test: lint linkcheck
Joey Armstronga8bc8e12022-12-04 07:06:59 -050093
Joey Armstrong36592e32022-11-28 09:00:28 -050094# doctest
95# coverage
96# linkcheck
Zack Williamsc6460c22019-12-18 14:54:43 -070097lint: doc8
Joey Armstronga8bc8e12022-12-04 07:06:59 -050098# include $(MAKEDIR)/lint/shell.mk
Zack Williams071eda22019-05-15 18:19:51 -070099
Zack Williams16042b62020-03-29 22:03:16 -0700100doc8: $(VENV_NAME) | $(OTHER_REPO_DOCS)
Zack Williamsc6460c22019-12-18 14:54:43 -0700101 source $</bin/activate ; set -u ;\
102 doc8 --max-line-length 119 \
Zack Williams16042b62020-03-29 22:03:16 -0700103 $$(find . -name \*.rst ! -path "*venv*" ! -path "*vendor*" ! -path "*repos*" )
Zack Williams071eda22019-05-15 18:19:51 -0700104
105# markdown linting
106# currently not enabled, should be added to lint target
107LINT_STYLE ?= mdl_strict.rb
108md-lint: | $(OTHER_REPO_DOCS)
109 @echo "markdownlint(mdl) version: `mdl --version`"
110 @echo "style config:"
111 @echo "---"
112 @cat $(LINT_STYLE)
113 @echo "---"
Zack Williams16042b62020-03-29 22:03:16 -0700114 mdl -s $(LINT_STYLE) `find -L $(SOURCEDIR) ! -path "./_$(VENV_NAME)/*" ! -path "./_build/*" ! -path "./repos/*" ! -path "*vendor*" -name "*.md"`
Zack Williams071eda22019-05-15 18:19:51 -0700115
116# clean up
117clean:
Joey Armstrong36592e32022-11-28 09:00:28 -0500118 $(RM) -r $(BUILDDIR) $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Zack Williams071eda22019-05-15 18:19:51 -0700119
Joey Armstrong36592e32022-11-28 09:00:28 -0500120clean-all sterile: clean
121 $(RM) -r $(VENV_NAME) repos
Zack Williams071eda22019-05-15 18:19:51 -0700122
Zack Williams071eda22019-05-15 18:19:51 -0700123# checkout the repos inside repos/ dir
124repos:
125 mkdir repos
126
127# build directory paths in repos/* to perform 'git clone <repo>' into
128CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
129
130# Host holding the git server
131REPO_HOST ?= https://gerrit.opencord.org
132
133# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
134# pre-populate it under repos/ with the specific commit to being validated
135SKIP_CHECKOUT ?=
136
Zack Williams88df4742019-12-20 08:24:47 -0700137# clone (only if doesn't exist)
Zack Williams071eda22019-05-15 18:19:51 -0700138$(CHECKOUT_REPOS): | repos
Zack Williams071eda22019-05-15 18:19:51 -0700139 if [ ! -d '$@' ] ;\
140 then git clone $(REPO_HOST)/$(@F) $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700141 fi
142
Zack Williams33085522020-02-28 11:41:01 -0700143# checkout correct ref if not under test, then copy subdirectories into main
Zack Williams17e34022019-12-20 13:51:54 -0700144# docs dir
Zack Williams071eda22019-05-15 18:19:51 -0700145$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
Zack Williams88df4742019-12-20 08:24:47 -0700146 if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
147 then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700148 cd "repos/$@" && git checkout $$GIT_REF ;\
Zack Williams88df4742019-12-20 08:24:47 -0700149 fi
Zack Williams17e34022019-12-20 13:51:54 -0700150 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
Zack Williams33085522020-02-28 11:41:01 -0700151 cp -r repos/$(@)$$GIT_SUBDIR $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -0700152
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100153# Build Robot documentation in voltha-system-tests and copy it into _static.
154_static/voltha-system-tests: | $(OTHER_REPO_DOCS)
155 make -C voltha-system-tests gendocs
156 mkdir -p $@
157 cp -r voltha-system-tests/gendocs/* $@
158
Andy Bavier39d67b12020-02-27 16:08:52 -0700159# Build Robot documentation in cord-tester and copy it into _static.
160_static/cord-tester: | $(OTHER_REPO_DOCS)
161 make -C cord-tester gendocs
162 mkdir -p $@
163 cp -r cord-tester/gendocs/* $@
164
Zack Williams071eda22019-05-15 18:19:51 -0700165# generate a list of git checksums suitable for updating git_refs
166freeze: repos
167 @for repo in $(OTHER_REPO_DOCS) ; do \
168 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700169 cd "repos/$$repo" > /dev/null ;\
Zack Williams071eda22019-05-15 18:19:51 -0700170 HEAD_SHA=`git rev-parse HEAD` ;\
171 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700172 cd ../.. ;\
Zack Williams071eda22019-05-15 18:19:51 -0700173 done
174
Zack Williams16042b62020-03-29 22:03:16 -0700175# build multiple versions
176multiversion: $(VENV_NAME) Makefile | prep $(OTHER_REPO_DOCS)
Zack Williams88df4742019-12-20 08:24:47 -0700177 source $</bin/activate ; set -u ;\
Zack Williams16042b62020-03-29 22:03:16 -0700178 sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
179 cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
Zack Williams88df4742019-12-20 08:24:47 -0700180
Zack Williams16042b62020-03-29 22:03:16 -0700181# prep target - used in sphinx-multiversion to properly link
182prep: | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Andy Bavier5dee6ae2020-01-29 16:03:40 -0700183
Zack Williams071eda22019-05-15 18:19:51 -0700184# Catch-all target: route all unknown targets to Sphinx using the new
185# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
Joey Armstrong36592e32022-11-28 09:00:28 -0500186# %: $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
187
Joey Armstrong1a9b7d12022-12-19 14:13:07 -0500188include $(MAKEDIR)/voltha/docs-catchall-targets.mk
Joey Armstrong36592e32022-11-28 09:00:28 -0500189$(voltha-docs-catchall): $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
190 @echo " ** CATCHALL: $@"
Zack Williamsc6460c22019-12-18 14:54:43 -0700191 source $</bin/activate ; set -u ;\
Zack Williams071eda22019-05-15 18:19:51 -0700192 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Joey Armstrong36592e32022-11-28 09:00:28 -0500193
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500194## -----------------------------------------------------------------------
195## -----------------------------------------------------------------------
196BROWSER ?= $(error Usage: $(MAKE) $@ BROWSER=)
197view-html:
198 "$(BROWSER)" _build/html/index.html
199
200## -----------------------------------------------------------------------
201## -----------------------------------------------------------------------
Joey Armstrong36592e32022-11-28 09:00:28 -0500202include $(MAKEDIR)/help/trailer.mk
203
204# [EOF]