Tabbed view with examples in landing page

[mziccard]

This PR addresses #129.

• Add a tabbed view for examples in the landing page
• Example for Compute/App Engine is kept as is, while I added an example for using the library outside of Compute/App Engine
• Add highlight.js to handle code formatting

Notes: the example uses AuthCredentials.createForJson so we should not update previous versions sites. If I am not mistaken Travis will use the new files from this PR for the next release.
You can have a look at the page here, comments are more than welcome.

[jgeewax]

Hmm - looks like we lost some of the syntax highlighting in that demo?

[mziccard]

@jgeewax You are right I forgot to add custom highlighting for constants. Could you double-check now?

[jgeewax]

As much as I hate how long we need our snippet to be (!) -- this LGTM :)

[aozarov]

Nice.

In AE and CE one also does not have to supply projectid. see here.

As of now, snapshot releases are only pushed maven (snapshot repository) and non snapshot releases are pushed to maven as well as creating and updating the site. So, I don't think this will be pushed by Travis as is. see here.

[mziccard]

@aozarov Yes, I meant that Travis detects when a release is pushed through $SITE_VERSION and only in that case builds (and publishes) the site for the new release. It this right? Merging this PR does not trigger any site build so older versions sites remain unchanged.

[aozarov]

@mziccard Right, however if we want it sooner than later we could push it manually (in a separate PR).

Do you still want to keep the explicit projectid for CE and AE? I think omitting it is nicer and consistent with not supplying the auth (that is tied for that project)....

[mziccard]

@aozarov I've just removed it:)

[aozarov]

Great, thanks. Why the empty line between options assignment and datastore?

[mziccard]

It's just there to separate the "environment" dependent part from the more functional one. Basically after the line the code is the same in all environments (and in the 2 tabs). But I am not particularly attached to it, so I can drop it if you prefer.

[aozarov]

+1 to remove that empty line.

[aozarov]

Thanks! another nit. Do you mind to change the CE/AE version to have only one line separator between imports and the code (similar to the other one).

[jgeewax]

I'm +1 to keeping a line separating env setup from Datastore specific stuff......

[aozarov]

I am -1 for that. The setup is actually service specific (each service has its own options, though they share a common code for setting common stuff).

DatastoreOptions options = DatastoreOptions.builder().build();

Datastore datastore = DatastoreFactory.instance().get(options);
KeyFactory keyFactory = datastore.newKeyFactory().kind(KIND);
...

That empty line between DatastoreOptions construction and Datastore construction seems wrong to me (and normally will not appear in user code). Instead, if we must, I would have a comment.

[jgeewax]

The way you have it written I'd far more readable to me.... It's already super long... I think a giant blob of text like that needs a little spacing... Like separate paragraphs in GH. Do we have a style guide reference saying they should be all one "paragraph"?

[aozarov]

The way I mentioned above is less readable to me (though I would not go as much as saying far) :)
We don't use spacing in this particular case in our code (test or samples).

This is what the Java style guide has to say about empty lines: vertical-whitespace.

You may argue that "Within method bodies, as needed to create logical groupings of statements." falls in this category but I think that is a weak argument. I would say that a space between constructing a service and using it would make more sense to me.

[jgeewax]

I think that's exactly the argument... Logical grouping of statements....

[aozarov]

Ok, than you have my answer/opinion.

[mziccard]

So what do we do then?:) Maybe @ajkannan can give us a third opinion.

[aozarov]

You can wait to get more opinions like @ajkannan or just decide yourself.

I think, this is a minor issue and can always be changed later (so the decision should
not block this PR).

Just to make my opinion clear is that I think current state should be change to:

1. Only 1 empty line between import and code, but more importantly be consistent in both examples.
2. No need for an empty line after DatastoreOptions creation (my top preference) or have another empty line after Datastore creation or have an empty line only after DatastoreOptions and Datastore creation.

[ajkannan]

I have a slight preference towards one line to separate the imports from code (and no other empty lines), but either way wouldn't be abhorrent in my book :)

[mziccard]

I updated last commit to remove the additional unnecessary line. You can see the updated version here.
There are 2 empty lines at the end of the CE/AE code to match the length of the "elsewhere" example. Otherwise the code box size changes everytime tab is changed, which is quite ugly:)