Moving to asciidoc based tooling + refdoc generation

Author: balopat

.gitignore

@@ -1,4 +1,5 @@
 out/
 examples/bazel/bazel-*
 *.new
-.idea/
+.idea/
+docs/generated

CONTRIBUTING.md renamed to CONTRIBUTING.adoc

@@ -1,8 +1,10 @@
 
-# How to Contribute
+= How to Contribute
 We'd love to accept your patches and contributions to this project. There are
 just a few small guidelines you need to follow.
-## Contributor License Agreement
+
+== Contributor License Agreement
+
 Contributions to this project must be accompanied by a Contributor License
 Agreement. You (or your employer) retain the copyright to your contribution,
 this simply gives us permission to use and redistribute your contributions as
@@ -11,8 +13,17 @@ your current agreements on file or to sign a new one.
 You generally only need to submit a CLA once, so if you've already submitted one
 (even if it was for a different project), you probably don't need to do it
 again.
-## Code reviews
+
+== Code reviews
 All submissions, including submissions by project members, require review. We
 use GitHub pull requests for this purpose. Consult
 [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
+information on using pull requests.
+
+== Contributing to documentation
+Contributing to docs is the same process as the code reviews - except that we recommend that you locally you can check the generated docs with 
+```
+make docs
+```
+And then open the generated docs/generated folder for `index.html` and `index.pdf`.
+

Makefile

@@ -36,11 +36,12 @@ SUPPORTED_PLATFORMS := linux-$(GOARCH) darwin-$(GOARCH) windows-$(GOARCH).exe
 BUILD_PACKAGE = $(REPOPATH)/cmd/skaffold
 
 VERSION_PACKAGE = $(REPOPATH)/pkg/skaffold/version
+COMMIT = $(shell git rev-parse HEAD)
 
 GO_LDFLAGS :="
 GO_LDFLAGS += -X $(VERSION_PACKAGE).version=$(VERSION)
 GO_LDFLAGS += -X $(VERSION_PACKAGE).buildDate=$(shell date +'%Y-%m-%dT%H:%M:%SZ')
-GO_LDFLAGS += -X $(VERSION_PACKAGE).gitCommit=$(shell git rev-parse HEAD)
+GO_LDFLAGS += -X $(VERSION_PACKAGE).gitCommit=$(COMMIT)
 GO_LDFLAGS += -X $(VERSION_PACKAGE).gitTreeState=$(if $(shell git status --porcelain),dirty,clean)
 GO_LDFLAGS +="
 
@@ -103,3 +104,25 @@ integration-in-docker:
 		-e GOOGLE_APPLICATION_CREDENTIALS=$(GOOGLE_APPLICATION_CREDENTIALS) \
 		gcr.io/$(GCP_PROJECT)/skaffold-integration
 
+.PHONY: docs
+docs:
+	rm -rf docs/generated
+	mkdir -p docs/generated
+	cp -R docs/css docs/generated/
+	docker run -v $(PWD):/documents/ asciidoctor/docker-asciidoctor \
+		asciidoctor \
+		-a version="$(VERSION)" \
+		-a commit="$(COMMIT)" \
+		-a data-uri \
+		-d book \
+		-D docs/generated/ \
+		docs/index.adoc
+	docker run -v $(PWD):/documents/ asciidoctor/docker-asciidoctor \
+		asciidoctor-pdf \
+		-a version="$(VERSION)" \
+		-a commit="$(COMMIT)" \
+		-a allow-uri-read \
+		-d book \
+		-a pdf \
+		-D docs/generated/ \
+		docs/index.adoc

README.adoc

@@ -0,0 +1,203 @@
+= Skaffold
+//tag::title[]
+:toc: macro
+ifndef::imagesdir[]
+:imagesdir: docs/img
+endif::[]
+//end::title[]
+
+[caption="Build status", link="https://travis-ci.org/GoogleContainerTools/skaffold"]
+image::https://travis-ci.org/GoogleContainerTools/skaffold.svg?branch=master[Build Status]
+
+//tag::intro[]
+Skaffold is a command line tool that facilitates continuous development for Kubernetes applications.
+You can iterate on your application source code locally then deploy to local or remote Kubernetes clusters.
+Skaffold handles the workflow for building, pushing and deploying your application.
+It can also be used in an automated context such as a CI/CD pipeline to leverage the same workflow and tooling when moving applications to production.
+//end::intro[]
+
+toc::[]
+
+//tag::features[]
+
+== Features
+
+-  No server-side component. No overhead to your cluster.
+-  Detect changes in your source code and automatically build/push/deploy.
+-  Image tag management. Stop worrying about updating the image tags in Kubernetes manifests to push out changes during development.
+-  Supports existing tooling and workflows. Build and deploy APIs make each implementation composable to support many different workflows.
+-  Support for multiple application components. Build and deploy only the pieces of your stack that have changed.
+-  Deploy regularly when saving files or run one off deployments using the same configuration.
+//end::features[]
+
+//tag::pluggability[]
+
+== Pluggability
+Skaffold has a pluggable architecture that allows you to choose the tools in the developer workflow that work best for you.
+
+image::plugability.png[]
+//end::pluggability[]
+
+//tag::operatingmodes[]
+
+= Operating modes
+== skaffold dev
+Updates your deployed application continually:
+
+-  Watches your source code and the dependencies of your docker images for changes and runs a build and deploy when changes are detected
+-  Streams logs from deployed containers
+-  Continuous build-deploy loop, only warn on errors
+
+== skaffold run
+Runs a Skaffold pipeline once, exits on any errors in the pipeline.
+Use for:
+
+-  Continuous integration or continuous deployment pipelines
+-  Sanity checking after iterating on your application
+//end::operatingmodes[]
+
+//tag::demo[]
+= Demo
+
+image::intro.gif[Demo]
+//end::demo[]
+//tag::getting_started_local[]
+
+= Getting Started with Local Tooling
+
+For getting started with Google Kubernetes Engine and Container Builder link:docs/quickstart-gke.adoc[go here.
+Otherwise continue
+below to get started with a local Kubernetes cluster.
+
+== Installation
+
+You will need the following components to get started with Skaffold:
+
+. skaffold
+   -  To download the latest Linux build, run:
+      -  `curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && chmod +x skaffold && sudo mv skaffold /usr/local/bin`
+   -  To download the latest OSX build, run:
+      -  `curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-darwin-amd64 && chmod +x skaffold && sudo mv skaffold /usr/local/bin`
+
+. Kubernetes Cluster
+   -  link:https://kubernetes.io/docs/tasks/tools/install-minikube/[Minikube],
+      link:https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster[GKE],
+      link:https://docs.docker.com/docker-for-windows/install/[Docker for Mac (Edge)] and link:https://docs.docker.com/docker-for-mac/install/[Docker for Windows (Edge)]
+      have been tested but any Kubernetes cluster will work.
+
+. link:https://kubernetes.io/docs/tasks/tools/install-kubectl/[kubectl]
+   -  If you're not using Minikube, configure the current-context with your target cluster for development
+
+. docker
+
+. Docker image registry
+   -  Your docker client should be configured to push to an external docker image repositor.
+If you're using a minikube or Docker for Desktop cluster, you can skip this requirement.
+   -  If you are using Google Container Registry (GCR), choose one of the following:
+        . Use `gcloud`'s Docker credential helper: Run link:https://cloud.google.com/sdk/gcloud/reference/auth/configure-docker[`gcloud auth configure-docker`]
+        . Install and configure GCR's standalone cred helper: link:https://github.com/GoogleCloudPlatform/docker-credential-gcr#installation-and-usage[`docker-credential-gcr`]
+        . Run `gcloud docker -a` before each development session.
+
+== Iterative Development
+
+. Clone this repository to get access to the examples.
+[source,shell]
+git clone https://github.com/GoogleContainerTools/skaffold
+
+. Change directories to the `getting-started` example.
+[source,shell]
+cd examples/getting-started
+
+. Run `skaffold dev`.
+
+[source,console]
+$ skaffold dev
+Starting build...
+Found [minikube] context, using local docker daemon.
+Sending build context to Docker daemon  6.144kB
+Step 1/5 : FROM golang:1.9.4-alpine3.7
+ ---> fb6e10bf973b
+Step 2/5 : WORKDIR /go/src/github.com/GoogleContainerTools/skaffold/examples/getting-started
+ ---> Using cache
+ ---> e9d19a54595b
+Step 3/5 : CMD ./app
+ ---> Using cache
+ ---> 154b6512c4d9
+Step 4/5 : COPY main.go .
+ ---> Using cache
+ ---> e097086e73a7
+Step 5/5 : RUN go build -o app main.go
+ ---> Using cache
+ ---> 9c4622e8f0e7
+Successfully built 9c4622e8f0e7
+Successfully tagged 930080f0965230e824a79b9e7eccffbd:latest
+Successfully tagged gcr.io/k8s-skaffold/skaffold-example:9c4622e8f0e7b5549a61a503bf73366a9cf7f7512aa8e9d64f3327a3c7fded1b
+Build complete in 657.426821ms
+Starting deploy...
+Deploying k8s-pod.yaml...
+Deploy complete in 173.770268ms
+[getting-started] Hello world!
+
+. Skaffold has done the following for you:
+
+   - Build an image from the local source code
+   - Tag it with its sha256
+   - Sets that image in the Kubernetes manifests defined in `skaffold.yaml`
+   - Deploy the Kubernetes manifests using `kubectl apply -f`
+
+. You will see the output of the pod that was deployed:
+[source,console]
+[getting-started] Hello world!
+[getting-started] Hello world!
+[getting-started] Hello world!
+
+Now, update `main.go`
+
+[source,diff]
+-----
+diff --git a/examples/getting-started/main.go b/examples/getting-started/main.go
+index 64b7bdfc..f95e053d 100644
+--- a/examples/getting-started/main.go
++++ b/examples/getting-started/main.go
+@@ -7,7 +7,7 @@ import (
+
+ func main() {
+        for {
+-               fmt.Println("Hello world!")
++               fmt.Println("Hello jerry!")
+                time.Sleep(time.Second * 1)
+        }
+ }
+-----
+
+Once you save the file, you should see the pipeline kick off again to redeploy your application:
+[source,console]
+[getting-started] Hello jerry!
+[getting-started] Hello jerry!
+
+== Run a deployment pipeline once
+There may be some cases where you don't want to run build and deploy continuously.
+To run once, use:
+[source,console]
+-----
+$ skaffold run
+-----
+
+//end::getting_started_local[]
+
+//tag::more_examples[]
+= More examples
+
+* link:./examples/helm-deployment[Deploying with Helm]
+* link:./examples/microservices[Microservices/Multiple applications]
+* link:./examples/annotated-skaffold.yaml[Annotated skaffold.yaml]
+//end::more_examples[]
+
+
+//tag::community[]
+= Community
+- link:https://groups.google.com/forum/#!forum/skaffold-users[skaffold-users mailing list]
+- link:https://kubernetes.slack.com/messages/CABQMSZA6/[#skaffold on Kubernetes Slack]
+//end::community[]
+
+