Generate docs when compiling protos (istio#3136)

.gitignore

@@ -28,6 +28,7 @@ lintconfig.gen.json
 # codegen stuff
 bin/protoc-gen-gogoslick*
 bin/protoc-min-version*
+bin/protoc-gen-docs*
 # Install generated files
 install/consul/istio.yaml
 install/eureka/istio.yaml

Gopkg.toml

@@ -30,6 +30,7 @@ required = [
   "github.com/gogo/protobuf/jsonpb",
   "github.com/gogo/protobuf/protoc-gen-gogoslick",
   "github.com/gogo/protobuf/gogoproto",
+  "github.com/istio/tools/protoc-gen-docs",
 ]
 
 ### END Mixer codegen deps
@@ -138,3 +139,7 @@ required = [
 [[constraint]]
   name = "code.cloudfoundry.org/copilot"
   revision = "ac2922c9b5cfb46d70befdc91612343e6e382811"
+
+[[constraint]]
+  branch = "master"
+  name = "github.com/istio/tools"

bin/mixer_codegen.sh

@@ -15,12 +15,20 @@ if [ ! -e $ROOT/Gopkg.lock ]; then
 fi
 
 GOGO_VERSION=$(sed -n '/gogo\/protobuf/,/\[\[projects/p' $ROOT/Gopkg.lock | grep version | sed -e 's/^[^\"]*\"//g' -e 's/\"//g')
+GENDOCS_VERSION=$(sed -n '/protoc-gen-docs/,/\[\[projects/p' $ROOT/Gopkg.lock | grep revision | sed -e 's/^[^\"]*\"//g' -e 's/\"//g')
 
 set -e
 
 outdir=$ROOT
 file=$ROOT
 protoc="$ROOT/bin/protoc-min-version-$GOGO_VERSION -version=3.5.0"
+
+# BUGBUG: we override the use of protoc-min-version here, since using
+#         that tool prevents warnings from protoc-gen-docs from being
+#         displayed. If protoc-min-version gets fixed to allow this
+#         data though, then remove this override
+protoc="protoc"
+
 optimport=$ROOT
 template=$ROOT
 
@@ -54,6 +62,8 @@ fi
 GOGOPROTO_PATH=vendor/github.com/gogo/protobuf
 GOGOSLICK=protoc-gen-gogoslick
 GOGOSLICK_PATH=$ROOT/$GOGOPROTO_PATH/$GOGOSLICK
+GENDOCS=protoc-gen-docs
+GENDOCS_PATH=vendor/github.com/istio/tools/$GENDOCS
 
 if [ ! -e $ROOT/bin/$GOGOSLICK-$GOGO_VERSION ]; then
 echo "Building protoc-gen-gogoslick..."
@@ -63,6 +73,14 @@ popd
 echo "Done."
 fi
 
+if [ ! -e $ROOT/bin/$GENDOCS-$GENDOCS_VERSION ]; then
+echo "Building protoc-gen-docs..."
+pushd $ROOT/$GENDOCS_PATH
+go build --pkgdir $GENDOCS_PATH -o $ROOT/bin/$GENDOCS-$GENDOCS_VERSION
+popd
+echo "Done."
+fi
+
 PROTOC_MIN_VERSION=protoc-min-version
 MIN_VERSION_PATH=$ROOT/$GOGOPROTO_PATH/$PROTOC_MIN_VERSION
 
@@ -125,7 +143,11 @@ done
 PLUGIN="--plugin=$ROOT/bin/protoc-gen-gogoslick-$GOGO_VERSION --gogoslick-${GOGO_VERSION}_out=plugins=grpc,$MAPPINGS:"
 PLUGIN+=$outdir
 
-# handle template code generation 
+GENDOCS_PLUGIN="--plugin=$ROOT/bin/$GENDOCS-$GENDOCS_VERSION --docs-${GENDOCS_VERSION}_out=warnings=true,mode=jekyll_html:"
+GENDOCS_PLUGIN_FILE=$GENDOCS_PLUGIN$(dirname "${file}")
+GENDOCS_PLUGIN_TEMPLATE=$GENDOCS_PLUGIN$(dirname "${template}")
+
+# handle template code generation
 if [ "$opttemplate" = true ]; then
 
   template_mappings=(
@@ -160,7 +182,7 @@ if [ "$opttemplate" = true ]; then
 
   # generate the descriptor set for the intermediate artifacts
   DESCRIPTOR="--include_imports --include_source_info --descriptor_set_out=$templateDS"
-  err=`$protoc $DESCRIPTOR $IMPORTS $PLUGIN $template`
+  err=`$protoc $DESCRIPTOR $IMPORTS $PLUGIN $GENDOCS_PLUGIN_TEMPLATE $template`
   if [ ! -z "$err" ]; then
     die "template generation failure: $err"; 
   fi
@@ -172,15 +194,14 @@ if [ "$opttemplate" = true ]; then
     die "template generation failure: $err"; 
   fi
 
-  #rm $templateDS
   rm $templateIP
   rm $templatePG
 
   exit 0
 fi
 
 # handle simple protoc-based generation
-err=`$protoc $IMPORTS $PLUGIN $file`
+err=`$protoc $IMPORTS $PLUGIN $GENDOCS_PLUGIN_FILE $file`
 if [ ! -z "$err" ]; then 
   die "generation failure: $err"; 
 fi