blob: 8ec67a94b03eb781b270468b0421e5e68a637eb3 [file] [log] [blame]
Zack Williamsad366132018-05-14 14:45:47 -07001# Makefile for building CORD docs site, guide.opencord.org
2# Building docs requires the following tools:
3# - Gitbook toolchain: https://toolchain.gitbook.com/setup.html
Zack Williams1cfa31a2018-06-28 15:35:17 -07004# - git
Zack Williamsad366132018-05-14 14:45:47 -07005# - NPM (for Gitbook and Swagger)
Zack Williamsad366132018-05-14 14:45:47 -07006# - linkchecker (for test target) http://wummel.github.io/linkchecker/
Zack Williams1cfa31a2018-06-28 15:35:17 -07007# - markdownlint (for lint target) https://github.com/markdownlint/markdownlint
Zack Williamsad366132018-05-14 14:45:47 -07008
9default: serve
10
Zack Williams1cfa31a2018-06-28 15:35:17 -070011# use bash for pushd/popd, and to fail quickly
12SHELL = bash -eu -o pipefail
Zack Williamsad366132018-05-14 14:45:47 -070013
Zack Williams1cfa31a2018-06-28 15:35:17 -070014# Other repos with documentation that's included in the gitbook
15# edit the `git_refs` file with the commit/tag/branch that you want to use
Scott Baker5ad952d2019-05-22 10:39:02 -070016OTHER_REPO_DOCS ?= att-workflow-driver cord-tester fabric fabric-crossconnect hippie-oss kubernetes-service olt-service onos-service openolt openstack rcord simpleexampleservice exampleservice vrouter xos xos-gui xos-tosca vtn-service cordctl
Zack Williams1cfa31a2018-06-28 15:35:17 -070017GENERATED_DOCS ?= # should be 'swagger', but currently broken
18ALL_DOCS ?= $(OTHER_REPO_DOCS) $(GENERATED_DOCS)
Zack Williamsad366132018-05-14 14:45:47 -070019
Zack Williams1cfa31a2018-06-28 15:35:17 -070020# build targets
21serve: | $(ALL_DOCS) gitbook-setup
Matteo Scandoloc93f6332018-05-25 15:19:43 -070022 npm start
Zack Williamsad366132018-05-14 14:45:47 -070023
Zack Williams1cfa31a2018-06-28 15:35:17 -070024build: _book
25
26_book: | $(ALL_DOCS) gitbook-setup
Zack Williamsad366132018-05-14 14:45:47 -070027 gitbook build
28
Zack Williams1cfa31a2018-06-28 15:35:17 -070029gitbook-setup:
Zack Williamsad366132018-05-14 14:45:47 -070030 gitbook init
31 gitbook install
32
Zack Williams1cfa31a2018-06-28 15:35:17 -070033clean:
34 rm -rf _book
35 rm -rf node_modules
36 rm -rf repos/*
37 rm -rf $(ALL_DOCS)
Zack Williamsad366132018-05-14 14:45:47 -070038
Zack Williams1cfa31a2018-06-28 15:35:17 -070039# testing targets
40test: lint linkcheck
41LINT_STYLE ?= mdl_relaxed.rb
Zack Williamsad366132018-05-14 14:45:47 -070042
Zack Williams1cfa31a2018-06-28 15:35:17 -070043lint: | $(OTHER_REPO_DOCS)
Zack Williamsad366132018-05-14 14:45:47 -070044 @echo "markdownlint(mdl) version: `mdl --version`"
45 @echo "style config:"
46 @echo "---"
Zack Williamsa719e4a2018-05-16 14:44:36 -070047 @cat $(LINT_STYLE)
Zack Williamsad366132018-05-14 14:45:47 -070048 @echo "---"
Zack Williams1cfa31a2018-06-28 15:35:17 -070049 mdl -s $(LINT_STYLE) `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./repos/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
Zack Williamsad366132018-05-14 14:45:47 -070050
Zack Williams1cfa31a2018-06-28 15:35:17 -070051linkcheck: $(ALL_DOCS) _book
Zack Williams32ee35f2019-04-02 08:12:34 -070052 linkchecker -a -f linkchecker.ini _book/
Luca Pretee62616d2018-05-24 14:40:18 -070053
Zack Williams1cfa31a2018-06-28 15:35:17 -070054# Host holding the git server
55REPO_HOST ?= https://gerrit.opencord.org
Zack Williamsad366132018-05-14 14:45:47 -070056
Zack Williams1cfa31a2018-06-28 15:35:17 -070057# checkout the repos inside repos/ dir
58repos:
59 mkdir repos
Matteo Scandolo821477f2018-05-29 08:43:13 -070060
Zack Williams1cfa31a2018-06-28 15:35:17 -070061# build directory paths in repos/* to perform 'git clone <repo>' into
62CHECKOUT_REPOS=$(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
Matteo Scandolo389c5632018-05-31 10:26:39 -070063
Zack Williamsa5acaf62018-07-03 16:28:49 -070064# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
65# pre-populate it under epos with the specific commit to being validated
66SKIP_CHECKOUT ?=
67
Zack Williams1cfa31a2018-06-28 15:35:17 -070068# clone (only if doesn't exist), then checkout ref in repos/*
69$(CHECKOUT_REPOS): git_refs | repos
70 GIT_REF=`grep '^$(@F) ' git_refs | awk '{print $$3}'` ;\
71 if [ ! -d '$@' ] ;\
Zack Williamsa5acaf62018-07-03 16:28:49 -070072 then git clone $(REPO_HOST)/$(@F) $@ ;\
73 fi ;\
74 if [ "$(SKIP_CHECKOUT)" = "$(@F)" ] ;\
75 then echo "Skipping checkout of repo $(SKIP_CHECKOUT) as it's being tested" ;\
76 else pushd $@ ;\
77 git checkout $$GIT_REF ;\
78 popd ;\
79 fi
Matteo Scandolo389c5632018-05-31 10:26:39 -070080
Zack Williams1cfa31a2018-06-28 15:35:17 -070081# link subdirectories (if applicable) into main docs dir
82$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
83 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
84 ln -s repos/$(@)$$GIT_SUBDIR $@
Matteo Scandolo4d516832018-06-12 07:58:31 -070085
Zack Williams1cfa31a2018-06-28 15:35:17 -070086# swagger docs generation
Zack Williamsad366132018-05-14 14:45:47 -070087swagger: xos
Zack Williams1cfa31a2018-06-28 15:35:17 -070088 pushd repos/xos/docs; make swagger_docs; popd;
Zack Williamsad366132018-05-14 14:45:47 -070089
Zack Williamsd5fa6d32018-07-20 20:20:41 -070090# generate a list of git checksums suitable for updating git_refs
91freeze: repos
92 @for repo in $(OTHER_REPO_DOCS) ; do \
93 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
94 cd "repos/$$repo" > /dev/null ;\
95 HEAD_SHA=`git rev-parse HEAD` ;\
96 printf "%-21s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
97 cd ../.. ;\
98 done
99