chore: add additional structure to generated docs (#3985)

* For API docs, wrap each generated document in `.docs-api`
* For markdown docs, wrap each generated document in `.docs-markdown`
* Remove the `h1` from API docs that contained only the component name
* Change the `h2` for API docs to be a friendlier title followed by an example import.
* Increase header level for API by one across the board (so that they're "under" the new `h2`)
* A few misc. docs fixes

Author: jelbourn

src/lib/input/autosize.ts

@@ -15,27 +15,21 @@ import {Directive, ElementRef, Input, OnInit} from '@angular/core';
   },
 })
 export class MdTextareaAutosize implements OnInit {
-  /** Minimum number of rows for this textarea. */
+  /** @deprecated Use mdAutosizeMinRows */
   @Input() minRows: number;
 
-  get mdAutosizeMinRows(): number {
-    return this.minRows;
-  }
-
-  @Input() set mdAutosizeMinRows(value: number) {
-    this.minRows = value;
-  }
+  /** Minimum number of rows for this textarea. */
+  @Input()
+  get mdAutosizeMinRows(): number { return this.minRows; }
+  set mdAutosizeMinRows(value: number) { this.minRows = value; }
 
-  /** Maximum number of rows for this textarea. */
+  /** @deprecated Use mdAutosizeMaxRows */
   @Input() maxRows: number;
 
-  get mdAutosizeMaxRows(): number {
-    return this.maxRows;
-  }
-
-  @Input() set mdAutosizeMaxRows(value: number) {
-    this.maxRows = value;
-  }
+  /** Minimum number of rows for this textarea. */
+  @Input()
+  get mdAutosizeMaxRows(): number { return this.maxRows; }
+  set mdAutosizeMaxRows(value: number) { this.maxRows = value; }
 
   /** Cached height of a textarea with a single row. */
   private _cachedLineHeight: number;

src/lib/input/input-container.ts

@@ -58,7 +58,7 @@ let nextUniqueId = 0;
 export class MdPlaceholder {}
 
 
-/** The hint directive, used to tag content as hint labels (going under the input). */
+/** Hint text to be shown underneath the input. */
 @Directive({
   selector: 'md-hint, mat-hint',
   host: {
@@ -75,7 +75,7 @@ export class MdHint {
   @Input() id: string = `md-input-hint-${nextUniqueId++}`;
 }
 
-/** Directive, used to display a single error message under the input. */
+/** Single error message to be shown underneath the input. */
 @Directive({
   selector: 'md-error, mat-error',
   host: {
@@ -84,21 +84,21 @@ export class MdHint {
 })
 export class MdErrorDirective { }
 
-/** The input prefix. */
+/** Prefix to be placed the the front of the input. */
 @Directive({
   selector: '[mdPrefix], [matPrefix], [md-prefix]'
 })
 export class MdPrefix {}
 
 
-/** The input suffix. */
+/** Suffix to be placed at the end of the input. */
 @Directive({
   selector: '[mdSuffix], [matSuffix], [md-suffix]'
 })
 export class MdSuffix {}
 
 
-/** The input directive, used to mark the input that `MdInputContainer` is wrapping. */
+/** Marker for the input element that `MdInputContainer` is wrapping. */
 @Directive({
   selector: `input[mdInput], textarea[mdInput], input[matInput], textarea[matInput]`,
   host: {
@@ -252,8 +252,7 @@ export class MdInputDirective {
 
 
 /**
- * Component that represents a text input. It encapsulates the <input> HTMLElement and
- * improve on its behaviour, along with styling it according to the Material Design.
+ * Container for text inputs that applies Material Design styling and behavior.
  */
 @Component({
   moduleId: module.id,

src/lib/radio/radio.md

@@ -1,9 +1,9 @@
-`<md-radio>` provides the same functionality as a native `<input type="radio">` enhanced with 
+`<md-radio>` provides the same functionality as a native `<input type="radio">` enhanced with
 Material Design styling and animations.  
 
 <!-- example(radio-overview) -->
 
-All radio buttons with the same `name` comprise a set from which only one may be selected at a time.
+All radio-buttons with the same `name` comprise a set from which only one may be selected at a time.
 
 ### Radio-button label
 The radio-button label is provided as the content to the `<md-checkbox>` element. The label can be 
@@ -18,7 +18,7 @@ specify an appropriate label.
 
 ### Radio groups
 Radio-buttons should typically be placed inside of an `<md-radio-group>` unless the DOM structure
-would make that impossible (e.g., radio buttons inside of table cells). The radio-group has a 
+would make that impossible (e.g., radio-buttons inside of table cells). The radio-group has a
 `value` property that reflects the currently selected radio-button inside of the group.
 
 Individual radio-buttons inside of a radio-group will inherit the `name` of the group.

tools/dgeni/templates/class.template.html

@@ -1,4 +1,6 @@
-<h3 class="docs-api-h3 docs-api-class-name">{$ class.name $}</h3>
+<h4 class="docs-api-h4 docs-api-class-name">
+  <code>{$ class.name $}</code>
+</h4>
 <p class="docs-api-class-description">{$ class.description $}</p>
 
 {%- if class.directiveExportAs -%}

tools/dgeni/templates/componentGroup.template.html

@@ -19,30 +19,36 @@
   {% include 'class.template.html' %}
 {% endmacro %}
 
-<h1 class="docs-api-h1">{$ doc.name $}</h1>
-<h2 class="docs-api-h2">
-  Module: <code>{$ doc.ngModule.name $}</code>
-</h2>
-
-
-{%- if doc.services.length -%}
-  <h2 class="docs-api-h2">Services</h2>
-  {% for service in doc.services %}
-    {$ class(service) $}
-  {% endfor %}
-{%- endif -%}
-
-
-{%- if doc.directives.length -%}
-  <h2>Directives</h2>
-  {% for directive in doc.directives %}
-    {$ class(directive) $}
-  {% endfor %}
-{%- endif -%}
-
-{%- if doc.additionalClasses.length -%}
-  <h2>Additional classes</h2>
-  {% for other in doc.additionalClasses %}
-    {$ class(other) $}
-  {% endfor %}
-{%- endif -%}
+<div class="docs-api">
+  <h2>
+    API reference for Angular Material {$ doc.name $}
+  </h2>
+
+  <p class="docs-api-module-import">
+    <code>
+      import {{$ doc.ngModule.name $}} from '@angular/material';
+    </code>
+  </p>
+
+  {%- if doc.services.length -%}
+    <h3 class="docs-api-h3">Services</h3>
+    {% for service in doc.services %}
+      {$ class(service) $}
+    {% endfor %}
+  {%- endif -%}
+
+
+  {%- if doc.directives.length -%}
+    <h3 class="docs-api-h3">Directives</h3>
+    {% for directive in doc.directives %}
+      {$ class(directive) $}
+    {% endfor %}
+  {%- endif -%}
+
+  {%- if doc.additionalClasses.length -%}
+    <h3 class="docs-api-h3">Additional classes</h3>
+    {% for other in doc.additionalClasses %}
+      {$ class(other) $}
+    {% endfor %}
+  {%- endif -%}
+</div>

tools/dgeni/templates/method-list.template.html

@@ -1,5 +1,5 @@
 {%- if methodList.length -%}
-  <h4 class="docs-api-h4 docs-api-method-header">Methods</h4>
+  <h5 class="docs-api-h5 docs-api-method-header">Methods</h5>
   {% for m in methodList %}
     {$ method(m) $}
   {% endfor %}

tools/dgeni/templates/property-list.template.html

@@ -1,5 +1,5 @@
 {%- if propertyList.length -%}
-  <h4 class="docs-api-h4 docs-api-method-header">Properties</h4>
+  <h5 class="docs-api-h5 docs-api-method-header">Properties</h5>
   <table class="docs-api-properties-table">
     <tr class="docs-api-properties-header-row">
       <th class="docs-api-properties-th">Name</th>

tools/gulp/tasks/docs.ts

@@ -41,7 +41,9 @@ const MARKDOWN_TAGS_TO_CLASS_ALIAS = [
   'td',
   'th',
   'tr',
-  'ul'
+  'ul',
+  'pre',
+  'code',
 ];
 
 task('docs', ['markdown-docs', 'highlight-docs', 'api-docs', 'minify-html-docs']);
@@ -95,20 +97,21 @@ task('minify-html-docs', ['api-docs'], () => {
 function transformMarkdownFiles(buffer: Buffer, file: any): string {
   let content = buffer.toString('utf-8');
 
-  /* Replace <!-- example(..) --> comments with HTML elements. */
+  // Replace <!-- example(..) --> comments with HTML elements.
   content = content.replace(EXAMPLE_PATTERN, (match: string, name: string) =>
     `<div material-docs-example="${name}"></div>`
   );
 
-  /* Replaces the URL in anchor elements inside of compiled markdown files. */
+  // Replace the URL in anchor elements inside of compiled markdown files.
   content = content.replace(LINK_PATTERN, (match: string, head: string, link: string) =>
     // The head is the first match of the RegExp and is necessary to ensure that the RegExp matches
     // an anchor element. The head will be then used to re-create the existing anchor element.
     // If the head is not prepended to the replaced value, then the first match will be lost.
     `${head} href="${fixMarkdownDocLinks(link, file.path)}"`
   );
 
-  return content;
+  // Finally, wrap the entire generated in a doc in a div with a specific class.
+  return `<div class="docs-markdown">${content}</div>`;
 }
 
 /** Fixes paths in the markdown files to work in the material-docs-io. */