docs: overhauled documentation

[callmehiphop]

Big Update Ahead!

This PR is one (of several) to move gcloud-node to the new gcloud-common docs app.

Notable changes:

• Completely removed old docs site
• Created a manifest.json file for the new site
• Updated all @example tags to follow JSDoc standard
• Created a new script to generate documentation JSON

TODOS

• Remove @linkcode tags in favor for custom type syntax ({module:service/object#method})
• Correct improper use of @mixes tag for ACL and IAM properties
• Update script to parse example comment syntax
• Move overviews to @classdesc tags
• Re-generate JSON for previous versions (separate PR to gh-pages) (docs: updated doc site and json schema #1098)
• version markdown files
• Wait for new doc app to be merged into gcloud-common (https://github.com/GoogleCloudPlatform/gcloud-common/pull/34)

@stephenplusplus let me know if there's anything I can do to make this easier to go through.. :)

[stephenplusplus]

Correct improper use of @mixes tag for ACL and IAM properties

What is the improper use?

[callmehiphop]

What is the improper use?

I think @mixin implies that we're inheriting either IAM or ACL, but we're actually just storing an instance as a property.. little bit different.

[stephenplusplus]

@mixin: A mixin provides functionality that is intended to be added to other objects. If desired, you can use the @mixin tag to indicate that an object is a mixin. You can then add the @mixes tag to objects that use the mixin.

JSDocs is pretty wild. What's a better way to describe (and document) the connection?

[callmehiphop]

What's a better way to describe (and document) the connection?

Still looking into that.. worst case scenario I'll just make @mixin work somehow!

[stephenplusplus]

Cool cool.

[callmehiphop]

But if I can make it work without it, one thing I'd strive to do is kill off all the empty variables..

[stephenplusplus]

Yes, please!

[quartzmo]

@callmehiphop Can you point me to where your build waits "for new doc app to be merged into gcloud-common"? I saw that got checked off but can't find the commit. I'm currently working on our gcloud-ruby json output using the docs app & assets that I manually copied from your gh-pages... But of course I need to automate.

[callmehiphop]

@quartzmo I was just waiting for the main app to get merged into gcloud-common, which it did yesterday via https://github.com/GoogleCloudPlatform/gcloud-common/pull/34. We have a hook that will generate JSON, etc. and didn't want to merge these changes in until all the other parts were good to go.