chore(travis): include dart doc generation

[chalin]

• Installs Dart SDK
• Installs ng2/dart sources from the pub package site.
• Re-enables doc build on Travis (which runs pub and dartdoc over ng2/dart).

Note: npm install -g gulp --no-optional has been removed since it does not appear to be needed.

Implements most of #1907.

[chalin]

@filipesilva @Foxandxss @wardbell : ready for review. Note that the extra wait for the doc generation only seems to be necessary when full logging is enabled; currently the logging level is set to warn, and doc generation takes ~20 min. (Otherwise I've seen it take ~40 min, though I'm not sure why there is such a difference).

cc: @kwalrath

[filipesilva]

There's a couple of things that I would like to understand better about this PR:

• The new WAIT env var strikes me as a red flag, why is it needed? can that value change? Having hardcoded waits is usually a brittle breaking point, or at the very least something that will overall delay CI.
• What are all these travis_fold commands? Won't this immediately break if I try to run the scripts locally? That sounds like a problem for using these scripts anywhere but travis.
• Seems like a lot of environment variables need to be set, which also sounds like it can be problematic for local runs.
• Dart now seems a .hard requirement for running deploy-install.sh, which means that I wouldn't be able to run it right now whereas before I could.

[chalin]

Thanks for your feedback.

• The new WAIT env var strikes me as a red flag, why is it needed?

See my previous comment.

Having hardcoded waits is usually a brittle breaking point,

It is no more brittle than the current default 10 min max.

or at the very least something that will overall delay CI.

Yes, it may.

What are all these travis_fold commands?

They help make the output manageable by having the output between start and end sections contained within a "fold" (headed by triangles in the left margin of the output).

Won't this immediately break if I try to run the scripts locally?

No, a value is always defined for the function, see env-set.sh.

That sounds like a problem for using these scripts anywhere but travis.

I suggest we follow what is done for the angular project and actually put all travis scripts in a separate folder so that it is understood that they are meant to be used for travis ... and might work locally, but that is not their primary purpose.

Seems like a lot of environment variables need to be set,

Not any more than those for angular.

which also sounds like it can be problematic for local runs.

These scripts are in support for Travis CI. I had assumed that when testing locally, doc developers would already have the necessary repos available as peers to the ng.io repo.

Dart now seems a .hard requirement for running deploy-install.sh, which means that I wouldn't be able to run it right now whereas before I could.

It runs fine in a Travis CI environment. Of course, I could make some parts be conditionally applied in a Travis environment only, and/or the presence of Dart tooling.

Currently, angular.io is the home to ng2 docs of all flavors, and under that premise, it seems essential to build all the docs as part of CI. Maybe I've been misdirected in my goal, any thoughts about this, @naomiblack?

The next steps, IMHO, include adding checks for broken links, etc. For that we want to do a whole site analysis.

[filipesilva]

I haven't checked out A2's scripts and was only comparing with the scripts we already had. That's probably why I found everything so strange.

I like the idea of a travis scripts folder, but would be worried that it would lead either repetition or having some scripts only there. Do you suppose we can have some middle ground on that, where is it possible to run locally run scripts for TS/Dart (separately, as not all authors do both), and still have all the extra tooling in travis only scripts?

[filipesilva]

I agree that we should build all docs on travis btw, just wanted to preserve scripts as a way to setup/reset local environments as well. Maybe it's too hard to have both at the moment.

[chalin]

I like the idea of a travis scripts folder, but would be worried that it would lead either repetition or having some scripts only there. Do you suppose we can have some middle ground ...

Yes, agreed. It would help to know which scripts are run locally. I was under the impression that scripts/deploy-install.sh would be used only for CI (given that most doc developers, IMHO, would tend to manage repo cloning by a separate mechanism). If not, I can add some conditional logic.

[filipesilva]

The script that I care about as a TS/JS author is examples-install.sh - because it's currently just for ts/js. Maybe the specific bits should be factored out.

The script that I care about as someone who does TS/JS releases is examples-install.sh and deploy-install.sh, again because of the ts/js focus. If the dart part of a site deploy fails my ability to fix it is limited... I can fix jade level stuff but anything that touches the examples I try not to touch.

[chalin]

Ok, thanks for the input on that. Let's see what can be done ... .

[chalin]

@filipesilva I have updated the scripts so that they can be run from the command line. I have moved out as much as I can from the env-set.sh script. Note that the examples-install scripts have not be touched. Please have a look.

[filipesilva]

LGTM Patrice, thank your for all the hard work in getting dart doc gen working on travis!

I'm seeing doc generation taking 7-8mins on Travis, whereas you mentioned 20m. Did you manage to cut it down further?

[chalin]

Ah, that is because it isn't actually building the Dart docs. I needed to adjust the gulpfile to switch to the default of all languages for the tasks: fullSiteBuildTasks = ['build-compile', 'check-serve', 'check-deploy']. Done.

[chalin]

@wardbell : ok, this is good to go! :)

[wardbell]

I'm out of my depth. Since @filipesilva approves, in it goes

[chalin]

Great!

Btw, @filipesilva @wardbell : if ever the extended timeout becomes an issue, we can always adjust the number. At least now the basic mechanism is is place so that all we need to do is change a number.