update dgeni templates and site CSS for new API design

[naomiblack]

We worked with a designer to come up with improved styling for the API doc pages. Implementing this has two parts:

• new CSS styles that dgeni can use to apply the new "denser, more structured" look
• work on dgeni templates to output the content as dictated by the new design, using the new CSS styles

The designer we worked with didn't have Angular expertise, so came up with a WIP PR (#585) where she applied the style changes to the output final pages to show what it should look like. The WIP is just for illustration; the work was done on the generated output files, not the source that is used to create them.

See attached PDF for the full design:

APIDoc_design-proposal.pdf

[pcharlebois]

List of tasks & priorities for API Doc:
Header

• Status Badges

Main content

• Layout changes - 2 column grids

- [ ] Typography changes - [ ] Tooltip hover

- [x] Live demo header for code examples (markdown) -- this should be global to all code on site, replacing the Live Plunkr link

- [ ] Styles for class details

- [x] Styles for Body Text—Link

- [x] Floating Menu

[naomiblack]

Please note that we do not yet have hooks for the Stable / Draft / Deprecated indicator output by dgeni, and I think we still need to figure out how to make "Improve This Doc" work. @IgorMinar @petebacondarwin.

[ericjim]

To accomplish this work the template file located in tools/api-builder/templates/class.template.html needs to be modified. @amitafr I'll walk you through it.

[ericjim]

Additional fields in the documentation are needed to [achieve the proposal](url
[achieve the proposal]%28https://github.com/angular/angular.io/files/193579/APIDoc_design-proposal.pdf%29), in particular there has to be a way to extract the text that will populate "What it does", "How to use", etc. @naomiblack.

Consider the following Angular 2 directive. There currently doesn't exist a predictable way of delimiting sections in the doc string. @petebacondarwin has discussed with me the possible intent of adding @howtouse, @whatitdoes, etc...tags that will match the text we need to be exposed and stylized in the doc site. However, a decision must be made on this @IgorMinar.

[naomiblack]

Updating with status for others. I ran this past @mhevery -- @howtouse etc sounds fine. We'll start by updating ng-Switch and trying it out.

One concern is that we'll need to update the Dart transformers to correctly output this for the Dart version of the API docs. Could you keep a list of the new annotations that you add so it's easy for me to get them all in one update later?

[ericjim]

@naomiblack I've made a list here #1028, I will be submitting a separate PR which adds support for these tags.

[ericjim]

Still a work in progress, but I've managed to get the dgeni+jade templates to work in our favour.

[ericjim]

Many of the things in the proposal have been implemented. I would say that we are missing the following:

Bar for code examples and live demo

Tooltips

Floating Footer in API Doc

[ghost]

@wardbell , you closed #585 due to the pending redesign of angular.io. Maybe this issue here should be closed, too?

[Foxandxss]

Indeed