blob: 56360b0bf82c193b7351a9fdadf6ef7db9699d9a [file] [log] [blame]
Zack Williams071eda22019-05-15 18:19:51 -07001# Makefile for Sphinx documentation
2
3# use bash for pushd/popd, and to fail quickly
4SHELL = bash -e -o pipefail
5
6# You can set these variables from the command line.
7SPHINXOPTS ?=
8SPHINXBUILD ?= sphinx-build
9SOURCEDIR ?= .
10BUILDDIR ?= _build
11
Zack Williams88df4742019-12-20 08:24:47 -070012# Other repos with documentation to include.
13# edit the `git_refs` file with the commit/tag/branch that you want to use
Andy Bavier39d67b12020-02-27 16:08:52 -070014OTHER_REPO_DOCS ?= bbsim voltha-go voltha-openolt-adapter voltha-openonu-adapter voltha-protos voltctl voltha-system-tests cord-tester
Zack Williams88df4742019-12-20 08:24:47 -070015
Zack Williams071eda22019-05-15 18:19:51 -070016# Put it first so that "make" without argument is like "make help".
17help: doc_venv
Zack Williamsc6460c22019-12-18 14:54:43 -070018 source $</bin/activate ; set -u ;\
Zack Williams071eda22019-05-15 18:19:51 -070019 $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
20
Zack Williams88df4742019-12-20 08:24:47 -070021.PHONY: help test lint reload Makefile prep
Zack Williams071eda22019-05-15 18:19:51 -070022
23# Create the virtualenv with all the tools installed
24doc_venv:
Zack Williams33085522020-02-28 11:41:01 -070025 virtualenv -p python3 doc_venv ;\
Zack Williamsc6460c22019-12-18 14:54:43 -070026 source $@/bin/activate ;\
Zack Williams071eda22019-05-15 18:19:51 -070027 pip install livereload ;\
28 pip install -r requirements.txt
29
30# automatically reload changes in browser as they're made
31reload: doc_venv
Zack Williamsc6460c22019-12-18 14:54:43 -070032 source $</bin/activate ; set -u ;\
Zack Williams071eda22019-05-15 18:19:51 -070033 sphinx-reload $(SOURCEDIR)
34
35# lint and link verification. linkcheck is part of sphinx
36test: lint linkcheck
37
Zack Williamsc6460c22019-12-18 14:54:43 -070038lint: doc8
Zack Williams071eda22019-05-15 18:19:51 -070039
Zack Williamsc6460c22019-12-18 14:54:43 -070040doc8: doc_venv | $(OTHER_REPO_DOCS)
41 source $</bin/activate ; set -u ;\
42 doc8 --max-line-length 119 \
Andy Bavier39d67b12020-02-27 16:08:52 -070043 $$(find . -name \*.rst ! -path "*doc_venv*" ! -path "*vendor*" ! -path "*repos/voltha-system-tests/vst_venv/*" ! -path "*repos/cord-tester/venv_cord/*")
Zack Williams071eda22019-05-15 18:19:51 -070044
45# markdown linting
46# currently not enabled, should be added to lint target
47LINT_STYLE ?= mdl_strict.rb
48md-lint: | $(OTHER_REPO_DOCS)
49 @echo "markdownlint(mdl) version: `mdl --version`"
50 @echo "style config:"
51 @echo "---"
52 @cat $(LINT_STYLE)
53 @echo "---"
54 mdl -s $(LINT_STYLE) `find -L $(SOURCEDIR) ! -path "./_doc_venv/*" ! -path "./_build/*" ! -path "./repos/*" ! -path "*vendor*" -name "*.md"`
55
56# clean up
57clean:
Andy Bavier39d67b12020-02-27 16:08:52 -070058 rm -rf $(BUILDDIR) $(OTHER_REPO_DOCS) _static/voltha-system-tests _static/cord-tester
Zack Williams071eda22019-05-15 18:19:51 -070059
60clean-all: clean
61 rm -rf doc_venv repos
62
Zack Williams071eda22019-05-15 18:19:51 -070063# checkout the repos inside repos/ dir
64repos:
65 mkdir repos
66
67# build directory paths in repos/* to perform 'git clone <repo>' into
68CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
69
70# Host holding the git server
71REPO_HOST ?= https://gerrit.opencord.org
72
73# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
74# pre-populate it under repos/ with the specific commit to being validated
75SKIP_CHECKOUT ?=
76
Zack Williams88df4742019-12-20 08:24:47 -070077# clone (only if doesn't exist)
Zack Williams071eda22019-05-15 18:19:51 -070078$(CHECKOUT_REPOS): | repos
Zack Williams071eda22019-05-15 18:19:51 -070079 if [ ! -d '$@' ] ;\
80 then git clone $(REPO_HOST)/$(@F) $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -070081 fi
82
Zack Williams33085522020-02-28 11:41:01 -070083# checkout correct ref if not under test, then copy subdirectories into main
Zack Williams17e34022019-12-20 13:51:54 -070084# docs dir
Zack Williams071eda22019-05-15 18:19:51 -070085$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
Zack Williams88df4742019-12-20 08:24:47 -070086 if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
87 then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -070088 cd "repos/$@" && git checkout $$GIT_REF ;\
Zack Williams88df4742019-12-20 08:24:47 -070089 fi
Zack Williams17e34022019-12-20 13:51:54 -070090 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
Zack Williams33085522020-02-28 11:41:01 -070091 cp -r repos/$(@)$$GIT_SUBDIR $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -070092
Andrea Campanella92bd59b2020-01-30 17:26:32 +010093# Build Robot documentation in voltha-system-tests and copy it into _static.
94_static/voltha-system-tests: | $(OTHER_REPO_DOCS)
95 make -C voltha-system-tests gendocs
96 mkdir -p $@
97 cp -r voltha-system-tests/gendocs/* $@
98
Andy Bavier39d67b12020-02-27 16:08:52 -070099# Build Robot documentation in cord-tester and copy it into _static.
100_static/cord-tester: | $(OTHER_REPO_DOCS)
101 make -C cord-tester gendocs
102 mkdir -p $@
103 cp -r cord-tester/gendocs/* $@
104
Zack Williams071eda22019-05-15 18:19:51 -0700105# generate a list of git checksums suitable for updating git_refs
106freeze: repos
107 @for repo in $(OTHER_REPO_DOCS) ; do \
108 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700109 cd "repos/$$repo" > /dev/null ;\
Zack Williams071eda22019-05-15 18:19:51 -0700110 HEAD_SHA=`git rev-parse HEAD` ;\
111 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700112 cd ../.. ;\
Zack Williams071eda22019-05-15 18:19:51 -0700113 done
114
Zack Williams88df4742019-12-20 08:24:47 -0700115# use sphinxcontrib-versioning to make a versioned copy of the
116# NOTE: document root is now in _build, not _build/html
117versioned: doc_venv Makefile | $(OTHER_REPO_DOCS)
118 source $</bin/activate ; set -u ;\
119 sphinx-versioning build -r master "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
120
121# prep target - used in sphinxcontrib-versioning to create versioned repos when
122# building multiple versions
123prep: | $(OTHER_REPO_DOCS)
124
Andy Bavier39d67b12020-02-27 16:08:52 -0700125html: doc_venv Makefile | $(OTHER_REPO_DOCS) _static/voltha-system-tests _static/cord-tester
Andy Bavier5dee6ae2020-01-29 16:03:40 -0700126 source $</bin/activate ; set -u ;\
127 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
128
Zack Williams071eda22019-05-15 18:19:51 -0700129# Catch-all target: route all unknown targets to Sphinx using the new
130# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
Zack Williamsc6460c22019-12-18 14:54:43 -0700131%: doc_venv Makefile | $(OTHER_REPO_DOCS)
132 source $</bin/activate ; set -u ;\
Zack Williams071eda22019-05-15 18:19:51 -0700133 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
134