blob: 027660a33490e1d74d81d2d2e70a14f458959db4 [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
14OTHER_REPO_DOCS ?= bbsim voltha-go voltha-openolt-adapter voltha-openonu-adapter voltha-protos
15
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:
25 virtualenv 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 \
43 $$(find . -name \*.rst ! -path "*doc_venv*" ! -path "*vendor*")
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:
58 rm -rf $(BUILDDIR) $(OTHER_REPO_DOCS)
59
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 Williams88df4742019-12-20 08:24:47 -070083# link subdirectories (if applicable) into main docs dir, then checkout ref if
84# not under test
Zack Williams071eda22019-05-15 18:19:51 -070085$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
86 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
Zack Williams88df4742019-12-20 08:24:47 -070087 ln -s repos/$(@)$$GIT_SUBDIR $@ ;\
88 if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
89 then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
90 pushd $@ ;\
91 git checkout $$GIT_REF ;\
92 popd ;\
93 fi
Zack Williams071eda22019-05-15 18:19:51 -070094
95# generate a list of git checksums suitable for updating git_refs
96freeze: repos
97 @for repo in $(OTHER_REPO_DOCS) ; do \
98 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
Zack Williams88df4742019-12-20 08:24:47 -070099 pushd "repos/$$repo" > /dev/null ;\
Zack Williams071eda22019-05-15 18:19:51 -0700100 HEAD_SHA=`git rev-parse HEAD` ;\
101 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
Zack Williams88df4742019-12-20 08:24:47 -0700102 popd ;\
Zack Williams071eda22019-05-15 18:19:51 -0700103 done
104
Zack Williams88df4742019-12-20 08:24:47 -0700105# use sphinxcontrib-versioning to make a versioned copy of the
106# NOTE: document root is now in _build, not _build/html
107versioned: doc_venv Makefile | $(OTHER_REPO_DOCS)
108 source $</bin/activate ; set -u ;\
109 sphinx-versioning build -r master "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
110
111# prep target - used in sphinxcontrib-versioning to create versioned repos when
112# building multiple versions
113prep: | $(OTHER_REPO_DOCS)
114
Zack Williams071eda22019-05-15 18:19:51 -0700115# Catch-all target: route all unknown targets to Sphinx using the new
116# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
Zack Williamsc6460c22019-12-18 14:54:43 -0700117%: doc_venv Makefile | $(OTHER_REPO_DOCS)
118 source $</bin/activate ; set -u ;\
Zack Williams071eda22019-05-15 18:19:51 -0700119 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
120