Merge "[CORD-3187]"
diff --git a/.gitignore b/.gitignore
index 27384fe..0b1f37c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@
npm-debug.log
node_modules
_book
+repos
xos/_book
venv-xosdocs
.DS_Store
diff --git a/Makefile b/Makefile
index f1d1b93..dc50e60 100644
--- a/Makefile
+++ b/Makefile
@@ -1,93 +1,82 @@
# Makefile for building CORD docs site, guide.opencord.org
# Building docs requires the following tools:
# - Gitbook toolchain: https://toolchain.gitbook.com/setup.html
+# - git
# - NPM (for Gitbook and Swagger)
-# - Python (for build glossary script)
# - linkchecker (for test target) http://wummel.github.io/linkchecker/
+# - markdownlint (for lint target) https://github.com/markdownlint/markdownlint
default: serve
-# use bash for pushd/popd, and to fail if commands within a pipe fail
-SHELL = bash -o pipefail
+# use bash for pushd/popd, and to fail quickly
+SHELL = bash -eu -o pipefail
-GENERATED_DOCS =
+# Other repos with documentation that's included in the gitbook
+# edit the `git_refs` file with the commit/tag/branch that you want to use
+OTHER_REPO_DOCS ?= cord-tester fabric hippie-oss kubernetes-service olt-service onos-service openolt openstack rcord simpleexampleservice vrouter xos xos-gui xos-tosca
+GENERATED_DOCS ?= # should be 'swagger', but currently broken
+ALL_DOCS ?= $(OTHER_REPO_DOCS) $(GENERATED_DOCS)
-LINT_STYLE ?= mdl_relaxed.rb
-
-serve: setup
+# build targets
+serve: | $(ALL_DOCS) gitbook-setup
npm start
-build: setup
+build: _book
+
+_book: | $(ALL_DOCS) gitbook-setup
gitbook build
-setup: automation-tools cord-tester simpleexampleservice openstack fabric hippie-oss kubernetes-service olt-service onos-service openolt rcord vrouter xos xos-gui xos-tosca swagger $(GENERATED_DOCS)
+gitbook-setup:
gitbook init
gitbook install
-test: linkcheck lint
+clean:
+ rm -rf _book
+ rm -rf node_modules
+ rm -rf repos/*
+ rm -rf $(ALL_DOCS)
-linkcheck: build
- linkchecker -a _book/
+# testing targets
+test: lint linkcheck
+LINT_STYLE ?= mdl_relaxed.rb
-lint:
+lint: | $(OTHER_REPO_DOCS)
@echo "markdownlint(mdl) version: `mdl --version`"
@echo "style config:"
@echo "---"
@cat $(LINT_STYLE)
@echo "---"
- mdl -s $(LINT_STYLE) `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
+ mdl -s $(LINT_STYLE) `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./repos/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
-# link directories that contain other documentation
-automation-tools:
- ln -s ../automation-tools automation-tools
+linkcheck: $(ALL_DOCS) _book
+ linkchecker -a _book/
-cord-tester:
- ln -s ../test/cord-tester/docs cord-tester
+# Host holding the git server
+REPO_HOST ?= https://gerrit.opencord.org
-fabric:
- ln -s ../orchestration/xos_services/fabric/docs fabric
+# checkout the repos inside repos/ dir
+repos:
+ mkdir repos
-hippie-oss:
- ln -s ../orchestration/xos_services/hippie-oss/docs hippie-oss
+# build directory paths in repos/* to perform 'git clone <repo>' into
+CHECKOUT_REPOS=$(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
-olt-service:
- ln -s ../orchestration/xos_services/olt-service/docs olt-service
+# clone (only if doesn't exist), then checkout ref in repos/*
+$(CHECKOUT_REPOS): git_refs | repos
+ GIT_REF=`grep '^$(@F) ' git_refs | awk '{print $$3}'` ;\
+ if [ ! -d '$@' ] ;\
+ then git clone $(REPO_HOST)/$(@F) $@ ;\
+ fi ;\
+ pushd $@ ;\
+ git checkout $$GIT_REF ;\
+ popd
-onos-service:
- ln -s ../orchestration/xos_services/onos-service/docs onos-service
+# link subdirectories (if applicable) into main docs dir
+$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
+ GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
+ ln -s repos/$(@)$$GIT_SUBDIR $@
-kubernetes-service:
- ln -s ../orchestration/xos_services/kubernetes-service/docs kubernetes-service
-
-openolt:
- ln -s ../incubator/openolt openolt
-
-rcord:
- ln -s ../orchestration/profiles/rcord/docs rcord
-
-vrouter:
- ln -s ../orchestration/xos_services/vrouter/docs vrouter
-
-openstack:
- ln -s ../orchestration/xos_services/openstack/docs openstack
-
-simpleexampleservice:
- ln -s ../orchestration/xos_services/simpleexampleservice/docs simpleexampleservice
-
-xos:
- ln -s ../orchestration/xos/docs xos
-
-xos-gui:
- ln -s ../orchestration/xos-gui/docs xos-gui
-
-xos-tosca:
- ln -s ../orchestration/xos-tosca/docs xos-tosca
-
+# swagger docs generation
swagger: xos
- pushd ../orchestration/xos/docs/; make swagger_docs; popd;
+ pushd repos/xos/docs; make swagger_docs; popd;
-clean:
- rm -rf $(GENERATED_DOCS)
- rm -rf _book
- rm -rf node_modules
- rm -rf openstack automation-tools cord-tester fabric hippie-oss kubernetes-service olt-service onos-service openolt rcord vrouter test xos xos-gui xos-tosca simpleexampleservice
diff --git a/examples/examples.md b/examples/examples.md
new file mode 100644
index 0000000..4f484f2
--- /dev/null
+++ b/examples/examples.md
@@ -0,0 +1,8 @@
+# Example Services
+
+There are two examples of services, which show how to create models and
+synchronizers:
+
+- ExampleService, which sets up a VM in Openstack
+- SimpleExampleService, which sets up a container in Kubernetes
+
diff --git a/git_refs b/git_refs
new file mode 100644
index 0000000..fcadce1
--- /dev/null
+++ b/git_refs
@@ -0,0 +1,28 @@
+# git_refs
+#
+# This file contains a list of repos, paths within those repos, and git
+# references (branch/tag/commit hash) that are checked out with `git checkout
+# <ref>` during creation of documentation.
+#
+# - First column is the git repo name
+# - Second column is the subdirectory of the repo to symlink into the
+# docs directory
+# - Third column is the reference (branch/tag/commit) to checkout
+
+_REPO NAME_ _DIR_ _REF_
+
+cord-tester /docs master
+fabric /docs master
+hippie-oss /docs master
+kubernetes-service /docs master
+olt-service /docs master
+onos-service /docs master
+openolt / master
+openstack /docs master
+rcord /docs master
+simpleexampleservice /docs master
+vrouter /docs master
+xos-gui /docs master
+xos-tosca /docs master
+xos /docs master
+