blob: 34575c2e841a663085f2b4230d767311e39b3fc4 [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
12# Put it first so that "make" without argument is like "make help".
13help: doc_venv
14 source ./doc_venv/bin/activate ;\
15 $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
16
17.PHONY: help test lint reload Makefile
18
19# Create the virtualenv with all the tools installed
20doc_venv:
21 virtualenv doc_venv ;\
22 source ./doc_venv/bin/activate ;\
23 pip install livereload ;\
24 pip install -r requirements.txt
25
26# automatically reload changes in browser as they're made
27reload: doc_venv
28 source ./doc_venv/bin/activate ;\
29 set -u ;\
30 sphinx-reload $(SOURCEDIR)
31
32# lint and link verification. linkcheck is part of sphinx
33test: lint linkcheck
34
35lint: rst-lint
36
37rst-lint: doc_venv | $(OTHER_REPO_DOCS)
38 source ./doc_venv/bin/activate ;\
39 set -u ;\
40 rstcheck -r $$(find . -name \*.rst ! -path "*doc_venv*" ! -path "./repos/*" ! -path "*vendor*")
41
42# markdown linting
43# currently not enabled, should be added to lint target
44LINT_STYLE ?= mdl_strict.rb
45md-lint: | $(OTHER_REPO_DOCS)
46 @echo "markdownlint(mdl) version: `mdl --version`"
47 @echo "style config:"
48 @echo "---"
49 @cat $(LINT_STYLE)
50 @echo "---"
51 mdl -s $(LINT_STYLE) `find -L $(SOURCEDIR) ! -path "./_doc_venv/*" ! -path "./_build/*" ! -path "./repos/*" ! -path "*vendor*" -name "*.md"`
52
53# clean up
54clean:
55 rm -rf $(BUILDDIR) $(OTHER_REPO_DOCS)
56
57clean-all: clean
58 rm -rf doc_venv repos
59
60# Other repos with documentation to include.
61# edit the `git_refs` file with the commit/tag/branch that you want to use
62OTHER_REPO_DOCS ?= bbsim voltha-go voltha-openolt-adapter voltha-openonu-adapter voltha-protos
63
64# checkout the repos inside repos/ dir
65repos:
66 mkdir repos
67
68# build directory paths in repos/* to perform 'git clone <repo>' into
69CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
70
71# Host holding the git server
72REPO_HOST ?= https://gerrit.opencord.org
73
74# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
75# pre-populate it under repos/ with the specific commit to being validated
76SKIP_CHECKOUT ?=
77
78# clone (only if doesn't exist), then checkout ref in repos/*
79$(CHECKOUT_REPOS): | repos
80 GIT_REF=`grep '^$(@F) ' git_refs | awk '{print $$3}'` ;\
81 if [ ! -d '$@' ] ;\
82 then git clone $(REPO_HOST)/$(@F) $@ ;\
83 fi ;\
84 if [ "$(SKIP_CHECKOUT)" = "$(@F)" ] ;\
85 then echo "Skipping checkout of repo $(SKIP_CHECKOUT) as it's being tested" ;\
86 else pushd $@ ;\
87 git checkout $$GIT_REF ;\
88 popd ;\
89 fi
90
91# link subdirectories (if applicable) into main docs dir
92$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
93 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
94 ln -s repos/$(@)$$GIT_SUBDIR $@
95
96# generate a list of git checksums suitable for updating git_refs
97freeze: repos
98 @for repo in $(OTHER_REPO_DOCS) ; do \
99 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
100 cd "repos/$$repo" > /dev/null ;\
101 HEAD_SHA=`git rev-parse HEAD` ;\
102 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
103 cd ../.. ;\
104 done
105
106# Catch-all target: route all unknown targets to Sphinx using the new
107# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
108%: Makefile doc_venv | $(OTHER_REPO_DOCS)
109 source ./doc_venv/bin/activate ;\
110 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
111