docs(api/dart): add support for generation and display

[chalin]

Fixes #1880, which has a detailed task breakdown.
Supersedes #1593.

Note about the API subsite design: I had to resort to using Jade extends/includes; hence disabling Harp _layout/partials.

cc: @naomiblack @kwalrath @ferhatb @keertip

[chalin]

@wardbell @Foxandxss : ready for review.

[chalin]

I forgot to mention that to build the docs do: an install (which patches terraforma), and then check-deploy.

Prerequisite: Ensure that you have the angular.io and Angular/Dart repos repos in the same directory, and the later must be named angular-dart --- if it isn't just create a link with that name pointing to the actual repo.

Commands:
Setup

./scripts/before-install.sh
./scripts/install.sh # this script now does the necessary patching

If you just want to build the Dart API docs:

gulp build-dart-api-docs --dgeni-log=warn  # drop the flag if you want `info` level messages as usual
gulp serve # to see the results at http://localhost:9000/

If you want to build all the docs:

gulp check-deploy --dgeni-log=warn  # drop the flag if you want `info` level messages as usual

[kwalrath]

Taking a look... First impression: nice!

The second thing I noticed is the lack of a language dropdown at /docs/dart/latest/api/ (or any page under it). Would it be possible to add it? (And add some reasonable behavior in the likely case that there's no equivalent page at the dart -> ts/js version of the URL.)

If a dropdown isn't practical, we should put "Dart" in that space, so it's easier to tell that you're in the Dart version of the API docs.

[chalin]

I chose to leave out the dropdown because IMHO maintaining a complete dart <-> ts/js mapping might be tricky and not really worth the effort (we can open a separate issue as a "feature request" so that we can track discussion about it). Leaving the dropdown there with only Dart is a good idea. I'll look into it.

[chalin]

@filipesilva @Foxandxss @wardbell : I just rebased. Note the following change:

• Renamed 'harp-compile' to 'check' (as in check-deploy without the deploy :).
• Created new 'harp-compile' that only does a harp compile; i.e., doesn't depend on 'build-docs' (where as 'check' does).

This makes it easier to selectively rebuild only parts of the docs and then quickly get harp to start compiling.

[filipesilva]

@chalin that change lgtm

[chalin]

@kwalrath : I've created #1895 for the API page language-cross-referencing issue. I'd like to suggest that nothing be done in the scope of this PR. We can explore the range of alternative solutions via #1895 and a follow up PR. Thoughts?

[kwalrath]

LGTM.

[kwalrath]

@filipesilva @Foxandxss @wardbell @naomiblack: Unless you object, I plan to merge this after confirming that I can, indeed, generate the docs. 2 pm Pacific time is my goal.

[wardbell]

Please no gulp task called check Check what? I don't approve.

I do understand the impulse. It comes down to naming. I strongly prefer one of these alternatives (in my preferred order)

1. an option on harp-compile such as harp-compile --no-build
2. new build-compile task that is check-deploy without the deploy.

[wardbell]

This could be build-compile

[wardbell]

Please also update the READM.md to explain these gulp tasks-and-options.

Otherwise, LGTM

[chalin]

@wardbell : named changed to build-compile.

More install / travis / gulpfile changes are on their way (to support Dart API docs building). I'll update the README then.

[wardbell]

LGTM. @kwalrath is free to merge 👍

[chalin]

Design note (cc @petebacondarwin): while originally I started writing a dgeni package for Dart API processing, I ran into problems -- due to my lack of mastery of the dgeni framework --- and so, in the hopes of making some progress, I switched to building a stand alone transformer from the dgeni package parts. Maybe this can be revised later, or, I might just write a revised API page generator in Dart :).