Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 1 | # 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 Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 4 | # - git |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 5 | # - NPM (for Gitbook and Swagger) |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 6 | # - linkchecker (for test target) http://wummel.github.io/linkchecker/ |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 7 | # - markdownlint (for lint target) https://github.com/markdownlint/markdownlint |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 8 | |
| 9 | default: serve |
| 10 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 11 | # use bash for pushd/popd, and to fail quickly |
| 12 | SHELL = bash -eu -o pipefail |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 13 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 14 | # 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 Baker | 5ad952d | 2019-05-22 10:39:02 -0700 | [diff] [blame] | 16 | OTHER_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 Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 17 | GENERATED_DOCS ?= # should be 'swagger', but currently broken |
| 18 | ALL_DOCS ?= $(OTHER_REPO_DOCS) $(GENERATED_DOCS) |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 19 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 20 | # build targets |
| 21 | serve: | $(ALL_DOCS) gitbook-setup |
Matteo Scandolo | c93f633 | 2018-05-25 15:19:43 -0700 | [diff] [blame] | 22 | npm start |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 23 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 24 | build: _book |
| 25 | |
| 26 | _book: | $(ALL_DOCS) gitbook-setup |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 27 | gitbook build |
| 28 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 29 | gitbook-setup: |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 30 | gitbook init |
| 31 | gitbook install |
| 32 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 33 | clean: |
| 34 | rm -rf _book |
| 35 | rm -rf node_modules |
| 36 | rm -rf repos/* |
| 37 | rm -rf $(ALL_DOCS) |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 38 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 39 | # testing targets |
| 40 | test: lint linkcheck |
| 41 | LINT_STYLE ?= mdl_relaxed.rb |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 42 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 43 | lint: | $(OTHER_REPO_DOCS) |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 44 | @echo "markdownlint(mdl) version: `mdl --version`" |
| 45 | @echo "style config:" |
| 46 | @echo "---" |
Zack Williams | a719e4a | 2018-05-16 14:44:36 -0700 | [diff] [blame] | 47 | @cat $(LINT_STYLE) |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 48 | @echo "---" |
Scott Baker | 70b7a1f | 2019-10-21 17:28:35 -0700 | [diff] [blame] | 49 | mdl -s $(LINT_STYLE) `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./repos/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" ! -path "*/vendor/*" -name "*.md"` |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 50 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 51 | linkcheck: $(ALL_DOCS) _book |
Zack Williams | 32ee35f | 2019-04-02 08:12:34 -0700 | [diff] [blame] | 52 | linkchecker -a -f linkchecker.ini _book/ |
Luca Prete | e62616d | 2018-05-24 14:40:18 -0700 | [diff] [blame] | 53 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 54 | # Host holding the git server |
| 55 | REPO_HOST ?= https://gerrit.opencord.org |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 56 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 57 | # checkout the repos inside repos/ dir |
| 58 | repos: |
| 59 | mkdir repos |
Matteo Scandolo | 821477f | 2018-05-29 08:43:13 -0700 | [diff] [blame] | 60 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 61 | # build directory paths in repos/* to perform 'git clone <repo>' into |
| 62 | CHECKOUT_REPOS=$(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo)) |
Matteo Scandolo | 389c563 | 2018-05-31 10:26:39 -0700 | [diff] [blame] | 63 | |
Zack Williams | a5acaf6 | 2018-07-03 16:28:49 -0700 | [diff] [blame] | 64 | # 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 |
| 66 | SKIP_CHECKOUT ?= |
| 67 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 68 | # 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 Williams | a5acaf6 | 2018-07-03 16:28:49 -0700 | [diff] [blame] | 72 | 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 Scandolo | 389c563 | 2018-05-31 10:26:39 -0700 | [diff] [blame] | 80 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 81 | # 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 Scandolo | 4d51683 | 2018-06-12 07:58:31 -0700 | [diff] [blame] | 85 | |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 86 | # swagger docs generation |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 87 | swagger: xos |
Zack Williams | 1cfa31a | 2018-06-28 15:35:17 -0700 | [diff] [blame] | 88 | pushd repos/xos/docs; make swagger_docs; popd; |
Zack Williams | ad36613 | 2018-05-14 14:45:47 -0700 | [diff] [blame] | 89 | |
Zack Williams | d5fa6d3 | 2018-07-20 20:20:41 -0700 | [diff] [blame] | 90 | # generate a list of git checksums suitable for updating git_refs |
| 91 | freeze: 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 | |