blob: e82b741a9d66ac6731dff862479cf0b3cf3f044c [file] [log] [blame]
Larry Peterson80143522018-06-28 10:43:40 -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
4# - NPM (for Gitbook and Swagger)
5# - Python (for build glossary script)
6# - linkchecker (for test target) http://wummel.github.io/linkchecker/
Zack Williamsda8a5d82017-09-08 12:45:14 -07007
Larry Peterson80143522018-06-28 10:43:40 -07008default: serve
Matteo Scandolo431781c2017-09-06 15:33:07 -07009
Larry Peterson80143522018-06-28 10:43:40 -070010# use bash for pushd/popd, and to fail if commands within a pipe fail
11SHELL = bash -o pipefail
Zack Williamsda8a5d82017-09-08 12:45:14 -070012
Larry Peterson80143522018-06-28 10:43:40 -070013GENERATED_DOCS =
Matteo Scandolo431781c2017-09-06 15:33:07 -070014
Larry Peterson80143522018-06-28 10:43:40 -070015LINT_STYLE ?= mdl_relaxed.rb
Zack Williams6c78f912018-06-21 10:56:24 -070016
Larry Peterson80143522018-06-28 10:43:40 -070017serve: setup
18 gitbook serve
Matteo Scandolo431781c2017-09-06 15:33:07 -070019
Larry Peterson80143522018-06-28 10:43:40 -070020build: setup
21 gitbook build
Zack Williamsda8a5d82017-09-08 12:45:14 -070022
Larry Peterson5adc6e92018-07-02 13:45:38 -070023setup: xos-gui xos-tosca kubernetes openstack onos simpleexampleservice exampleservice
Larry Peterson80143522018-06-28 10:43:40 -070024 gitbook init
25 gitbook install
Matteo Scandolo431781c2017-09-06 15:33:07 -070026
Larry Peterson80143522018-06-28 10:43:40 -070027test: linkcheck lint
28
29linkcheck: build
30 linkchecker -a _book/
31
32lint:
33 @echo "markdownlint(mdl) version: `mdl --version`"
34 @echo "style config:"
35 @echo "---"
36 @cat $(LINT_STYLE)
37 @echo "---"
38 mdl -s $(LINT_STYLE) `find -L . ! -path "./_book/*" ! -path "./node_modules/*" -name "*.md"`
39
40# link directories that contain other documentation
41xos-gui:
42 ln -s ../../xos-gui/docs xos-gui
43
44xos-tosca:
45 ln -s ../../xos-tosca/docs xos-tosca
46
Larry Peterson5adc6e92018-07-02 13:45:38 -070047kubernetes:
48 ln -s ../../services/kubernetes-service/docs kubernetes
49
50openstack:
51 ln -s ../../services/openstack/docs openstack
52
53onos:
54 ln -s ../../services/onos-service/docs onos
55
56exampleservice:
57 ln -s ../../services/exampleservice/docs exampleservice
58
59simpleexampleservice:
60 ln -s ../../services/simpleexampleservice/docs simpleexampleservice
61
62
Larry Petersonb658e8b2018-06-29 09:21:16 -070063# HOW TO
64# - load the virtual env (https://guide.opencord.org/xos/dev/local_env.html)
65# - run `make`
66# - open the browser at `http://127.0.0.1:8080/ui`
67# - you'll see the 'core' apis
68# - you can see a list of available apis at `http://127.0.0.1:8080/specs/`
69# - just replace the swagger file (top bar) with another one to see different APIs (to be improved)
Larry Peterson80143522018-06-28 10:43:40 -070070
Larry Petersonb658e8b2018-06-29 09:21:16 -070071DOCSDIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
72
73swagger: swagger_clean swagger_docs swagger_serve_spec
74
75venv-xosdocs:
76 ./venv-xosdocs.sh
77
78swagger_docs: venv-xosdocs
79 bash -c 'source $(DOCSDIR)venv-xosdocs/bin/activate && python $(DOCSDIR)scripts/swagger_docs.py'
80
81swagger_clean:
82 rm -rf swagger/specs/*
83
84venv_clean:
85 rm -rf $(DOCSDIR)venv-xosdocs
86
87swagger_serve_spec:
88 http-server --cors ./swagger
89
90clean: swagger_clean venv_clean
Larry Peterson80143522018-06-28 10:43:40 -070091 rm -rf $(GENERATED_DOCS)
92 rm -rf _book
93 rm -rf node_modules
Larry Peterson5adc6e92018-07-02 13:45:38 -070094 rm -rf xos xos-gui xos-tosca kubernetes openstack onos simpleexampleservice exampleservice