Add build-chain doc

_build_cfg.yml

@@ -119,6 +119,8 @@ Topics:
     File: authentication
   - Name: Config Generation
     File: generate_cmd
+  - Name: Output build dependencies
+    File: output_deps 
 
 ---
 Name: Writing OpenShift Images

using_openshift/output_deps.adoc

@@ -0,0 +1,54 @@
+= Dependency tree generation
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title: 
+
+toc::[]
+
+== Overview
+`build-chain` is an experimental command-line tool for OpenShift v3. This tool will start at the imagerepo:tag specified and determine what Builds will be triggered (due to ImageChangeTriggers on the BuildConfig) when this imagerepo:tag is updated. Further, it analyzes the output of those Builds to determine if they in turn update another imagerepo:tag. If they do, the tool continues to follow the dependency tree. It then outputs the total graph of what imagerepo:tags will be impacted by an update to the top level imagerepo:tag. The default output is set to JSON but the user can also choose between DOT and AST.
+
+
+== Examples
+
+
+Build dependency tree for the specified image repository with the specified tag in the current namespace and output it in JSON
+----
+$ openshift ex build-chain [image-repository]:[tag]
+----
+
+Build and output the dependency tree for the specified image repository with 'latest' tag in 'testing' namespace using DOT syntax
+----
+$ openshift ex build-chain [image-repository] -o dot -n testing
+----
+
+Build dependency trees for all tags in the specified image repository
+----
+$ openshift ex build-chain [image-repository] --all-tags
+----
+
+Build dependency trees for all tags of all image repositories in the current namespace and output them in JSON
+----
+$ openshift ex build-chain
+----
+
+Build dependency trees for all tags of all image repositories across all namespaces and dump them in AST
+----
+$ openshift ex build-chain --all -o ast
+----
+
+
+== Output
+
+The default output of `build-chain` is set to JSON but there is also support for DOT and AST. AST is used mostly for debugging, while with DOT the user can visualize the output of `build-chain` by using the `dot` utility of the GraphViz library.
+
+----
+$ openshift ex build-chain [image-repository]:[tag] -o dot > tree.dot
+$ dot -Tps tree.dot -o tree.ps
+----
+
+The DOT output from the build-chain utility gets parsed with the DOT parser so supposing `build-chain` doesn't error out, (most probably by invalid build configurations) then the user should get the dependency tree visualized in `tree.ps`.