docs-styles(build): Operationalize doc styles build

[AlmeroSteyn]

Automated process to build a CSS file for the Angular 2 documentation examples.

The process is driven by using the LESS source from Bootstrap CSS. By overriding the LESS variables and including other style overrides in the LESS build a single stylesheet is created that provides the Design approved example styles.

It is integrated in the gulp add-example-boilerplate and the _copy-example-boilerplate tasks.

Remaining steps (after merging to master):

• Get @naomiblack approval of the styles-in-action
• New PR to rename a2docs.css to sample.css which will propagate the style change to all doc samples.

[Foxandxss]

So from now own with ditch styles.css over this?

[AlmeroSteyn]

Yes, this will and should cater for all styling requirements. Should be able to use as little or as much as the example require. Once no examples depend on either bootstrap.css directly or styles.css anymore, both will be removed from the examples.

[wardbell]

There's a race condition in which the gulp plunker-builder task starts before the _copy-example-boilerplate task updates the samples with shared files from _examples. This race may have been there all along. This PR revealed it ... because the new a2docs.css file didn't show up in time and therefore wasn't included in the plunkers.

Fix that before proceeding with this PR

Please note: this PR creates the new a2docs.css file and populates the samples with it. But it does not change the way samples display because they don't know about it.

When we have confirmed that we like this new css file - a @naomiblack task - we'll need another PR (TBD) that propagates it to all doc samples by changing the generated filename from a2docs.css to styles.css; this works because all samples install styles.css today and the new a2docs.css style sheet incorporates everything currently in styles.css (to be confirmed).

[googlebot]

We found a Contributor License Agreement for you (the sender of this pull request) and all commit authors, but as best as we can tell these commits were authored by someone else. If that's the case, please add them to this pull request and have them confirm that they're okay with these commits being contributed to Google. If we're mistaken and you did author these commits, just reply here to confirm.

[googlebot]

We found a Contributor License Agreement for you (the sender of this pull request) and all commit authors, but as best as we can tell these commits were authored by someone else. If that's the case, please add them to this pull request and have them confirm that they're okay with these commits being contributed to Google. If we're mistaken and you did author these commits, just reply here to confirm.

[Foxandxss]

I fixed the race condition by sending a done parameter which gulp supports.

The problem is that we would like to have the new a2docs.css in e2e tests.

We were never "waiting" for copyExampleBoilerplate to finish copying on e2e because the other tasks would take way more time than that so when the tests were to run, everything was copied. That didn't change now.

So as soon as you double check that the race condition is gone (and remove the gutil.log) we could merge this and if you want, look for a better solution for this.

I could present that alternative solution in a different PR to not clutter this one.

[wardbell]

Thank you, @AlmeroSteyn ! And @Foxandxss for taking it the last mile.