Add docs and tutorial for buildpacks

[priyawadhwa]

Add docs with tutorial for using skaffold with buildpacks via
the custom builder.

depends on #2893 (merged)

[codecov]

Codecov Report

Merging #2879 into master will not change coverage.
The diff coverage is n/a.

Impacted Files	Coverage Δ
pkg/skaffold/server/server.go	58.57% <0%> (ø)	⬆️

[container-tools-bot]

Error creating deployment docs-controller-deployment-2879, please visit https://storage.googleapis.com/webhook-logs/logs-2879-1568411607494563296 to view logs.

[tejal29]

I added the label docs-modifications to see the changes, but looks like its broken due to #2884

Great start! some nits.
Will check again when docs are generated.

[container-tools-bot]

Error creating deployment docs-controller-deployment-2879, please visit https://storage.googleapis.com/webhook-logs/logs-2879-1568414435741304973 to view logs.

[container-tools-bot]

Error creating deployment docs-controller-deployment-2879, please visit https://storage.googleapis.com/webhook-logs/logs-2879-1568443021185774710 to view logs.

[tejal29]

@priyawadhwa Please rebase so we can check if #2884 fixed the issue

[tejal29]

There is another error

Error: Error building site: "/app/docs/content/en/docs/how-tos/buildpacks/_index.md:37:1": failed to 
render shortcode "readfile": failed to process shortcode: 
"/app/docs/layouts/shortcodes/readfile.html:1:47": execute of template failed: template: 
shortcodes/readfile.html:1:47: executing "shortcodes/readfile.html" at <readFile>: error calling 
readFile: file "samples/buildpacks/Skaffold.yaml" does not exist

[container-tools-bot]

Please visit http://34.94.71.232:1313 to view changes to the docs.

[priyawadhwa]

Hey @tejal29 -- incorporated your changes PTAL

[container-tools-bot]

Please visit http://34.94.233.95:1313 to view changes to the docs.

[container-tools-bot]

Please visit http://34.94.233.95:1313 to view changes to the docs.

[container-tools-bot]

Error creating deployment docs-controller-deployment-2879, please visit https://storage.googleapis.com/webhook-logs/logs-2879-1568663570220304046 to view logs.

[container-tools-bot]

Error creating deployment, please see controller logs for details.

[tejal29]

Sorry, just a few more nits.

I am trying to see if we can make this tutorial as complete as possible.
If a user is landing on this page directly. (via google search results)

It would be good to link skaffold's getting started doc.
E.g. See https://cloud.google.com/go/getting-started/tutorial-app#before-you-begin

You can either,
Explicitly mention,

• Before you being, please see our getting started guide at http://skaffold.dev/docs/getting-started/#before-you-begin
• Or, like this page https://cloud.google.com/go/getting-started/using-structured-data
  See how they mention

This page is part of a multi-page tutorial. 
To start from the beginning and read the setup instructions, go to Go Bookshelf app.

We can also do something similar and say

This page describes how to use Buildpacks with skaffold. 
To learn more about how to set up skaffold, see http://skaffold.dev/docs/getting-started

I don't mind either approach.

We should also have "Before you begin" Section and explicitly mention installing pack and docker.
Some users might skip it because its not mentioned :)

And then finally, a section on Cleaning Up.

[tejal29]

Lets try to add a one line description on what the example does so that user's know what they are installing.
e.g. https://cloud.google.com/go/getting-started/tutorial-app

Suggested change

	Clone the Skaffold buildpacks [example](https://github.com/GoogleContainerTools/Skaffold/blob/master/examples/buildpacks/) for sample code.
	In this tutorial, you will deploy a single go based file app on a pod.
	Clone the Skaffold buildpacks [example](https://github.com/GoogleContainerTools/Skaffold/blob/master/examples/buildpacks/) for sample code.

[tejal29]

Do we have cluster step up steps somewhere that we can point users to if they have never set up a cluster kubectl ?

[tejal29]

I think the getting-started guide might have it. If not we shd add it there.
Maybe we can do that in a separate PR.

[tejal29]

@priyawadhwa Can you also please break this PR into 2.

1. one with no user impact and just example.
   • Every example in examples/ should be tested. So we should add test it.
2. Actual docs changes

This could be an example on how to add break docs into smaller changes.

thanks
Tejal

[priyawadhwa]

@tejal29 thanks for the feedback, I've incorporated it --- PTAL!

[tejal29]

cool. @priyawadhwa changes looks great! will take a look at the generated docs.

[container-tools-bot]

Please visit http://34.94.71.232:1313 to view changes to the docs.

[tejal29]

Can you also link the http://skaffold.dev/docs/how-tos/builders/#custom-build-script-run-locally here. I think users might need help on what $image and $PUSH_IMAGE is.

[tejal29]

nit: k8s-skaffold will be replaced by <your repo>