Docs target (#2991)

* docs_target: add target and script to validate mkdocs

remove /*...*/ comments in doc/

* docs_target: fail build when yml has errors

* docs_target: test command result

* docs_target: add missing backtick

* docs_target: ensure use of python2

* docs_target: add python deps needed

* docs_target: add python deps

* docs_target: make sure pip is upgraded

Makefile

@@ -5,7 +5,7 @@ FMT = $(ROOT)/make/erlang-formatter-master/fmt.sh
 
 KAZOODIRS = core/Makefile applications/Makefile
 
-.PHONY: $(KAZOODIRS) deps core apps xref xref_release dialyze dialyze-it dialyze-apps dialyze-core dialyze-kazoo clean clean-test clean-release build-release build-ci-release tar-release release read-release-cookie elvis install ci diff fmt bump-copyright apis validate-swagger coverage-report fs-headers
+.PHONY: $(KAZOODIRS) deps core apps xref xref_release dialyze dialyze-it dialyze-apps dialyze-core dialyze-kazoo clean clean-test clean-release build-release build-ci-release tar-release release read-release-cookie elvis install ci diff fmt bump-copyright apis validate-swagger coverage-report fs-headers docs
 
 all: compile rel/dev-vm.args
 
@@ -193,6 +193,9 @@ apis:
 	@$(ROOT)/scripts/format-json.sh applications/crossbar/priv/api/*.json
 	@ERL_LIBS=deps/:core/:applications/ $(ROOT)/scripts/generate-fs-headers-hrl.escript
 
+docs:
+	$(ROOT)/scripts/validate_mkdocs.py
+
 fs-headers:
 	@ERL_LIBS=deps/:core/:applications/ $(ROOT)/scripts/generate-fs-headers-hrl.escript
 

circle.yml

@@ -19,6 +19,8 @@ dependencies:
   pre:
       - bash ./scripts/circleci-build-erlang.sh:
           timeout: 1800
+      - pip install --upgrade pip
+      - pip install PyYAML
 
 test:
   pre:
@@ -34,6 +36,7 @@ test:
     - . ~/.kerl/$OTP_VERSION/activate && make code_checks
     - ./scripts/validate-js.sh $($CHANGED)
     - . ~/.kerl/$OTP_VERSION/activate && make apis
+    - make docs
     - make validate-swagger
     - |
       if [[ 0 -ne `git status --porcelain | wc -l` ]]; then

doc/engineering/dialyzer.md

@@ -1,7 +1,3 @@
-/*
-Section: Kazoo
-Title: Dialyzer
-*/
 
 # Using Dialyzer on Kazoo
 

doc/engineering/releases.md

@@ -1,7 +1,3 @@
-/*
-Section: Kazoo
-Title: Releases
-*/
 
 # How to use Erlang releases with Kazoo
 

doc/installation.md

@@ -15,6 +15,13 @@ $ sudo apt-get install build-essential libxslt-dev \
 
 Note: `htmldoc` is required only if [you want to be able to download PDFs](./announcements.md#company-directory-pdf).
 
+#### Docs-relatd
+
+When running `make docs`, some Python libraries are useful:
+
+```shell
+$ sudo apt-get install python2.7 python-yaml
+```
 
 ### Erlang
 

doc/kazoocon/pivot2014.md

@@ -1,8 +1,3 @@
-/*
-Section: Pivot
-Title: Pivot KazooCon 2014 Demo
-Language: en-US
-*/
 
 # Infrastructure by Pastie.org
 

doc/mkdocs/mkdocs.yml

@@ -1,5 +1,4 @@
 site_name: Dev Reference
-theme: null
 theme_dir: '2600Hz_theme'
 
 pages:
@@ -78,7 +77,7 @@ pages:
     - 'Twiml':
       - 'applications/pivot/doc/twiml/README.md'
     - 'Tutorials':
-      - 'applications/pivot/doc/kazoocon-2014.md'
+      - 'doc/kazoocon/pivot2014.md'
     - 'Known_Issues':
       - 'applications/pivot/doc/issues.md'
     - 'Kazoo':

doc/reference/caller_id_formatting.md

@@ -1,7 +1,3 @@
-/*
-Section: Kazoo
-Title: Caller ID Formatting
-*/
 
 # Caller ID Formatting
 

doc/reference/routing.md

@@ -1,9 +1,3 @@
-/*
-Section: Reference
-Title: Rating and Limits
-Language: en-US
-Version: 3.22
-*/
 
 # Rating and Limits
 

scripts/validate_mkdocs.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python2
+from __future__ import print_function
+
+import yaml, os.path, sys
+
+# from https://stackoverflow.com/questions/5574702/how-to-print-to-stderr-in-python
+def eprint(*args, **kwargs):
+    print(*args, file=sys.stderr, **kwargs)
+
+def parse_page_dict(errors_detected, kv):
+    (header, pages) = kv
+    if pages is None:
+        eprint("section ", header, " is incomplete")
+        return True
+    else:
+        return parse_page(errors_detected, pages)
+
+def parse_page_string(errors_detected, page):
+    if "index.md" != page and (not os.path.isfile(page)):
+        eprint("page ", page, " is not valid")
+        return True
+    else:
+        return errors_detected
+
+def parse_page(errors_detected, page):
+    "parse a page for existence"
+    if isinstance(page, dict):
+        return reduce(parse_page_dict, page.items(), errors_detected)
+    elif isinstance(page, list):
+        return reduce(parse_page, page, errors_detected)
+    elif isinstance(page, str):
+        return parse_page_string(errors_detected, page)
+    else:
+        return errors_detected
+
+stream = open("doc/mkdocs/mkdocs.yml", 'r')
+mkdocs = yaml.load_all(stream)
+errors_detected = False
+
+for doc in mkdocs:
+    for k,v in doc.items():
+        if "pages" == k:
+            errors_detected = parse_page(False, v)
+
+if errors_detected:
+    sys.exit(1)