build(docs): show exported constants in docs (#13168)

devversion · vivian-hu-zz · commit 6a7327351f76 · 2018-10-04T10:11:09.000-07:00
* Currently constants which are exported, will not show up in the docs. This introduces support for displaying `constants` in the docs.
* Also creates a Nunjucks plugin that supports highlighting specific code snippets. This is helpful when rendering a type in the docs (similar to angular/aio)
* Marks most animation constants as `@docs-private` because those shouldn't be relevant to users.
diff --git a/src/cdk/overlay/overlay-module.ts b/src/cdk/overlay/overlay-module.ts
@@ -36,6 +36,7 @@ export class OverlayModule {}
 /**
  * @deprecated Use `OverlayModule` instead.
  * @breaking-change 7.0.0
+ * @docs-private
  */
 export const OVERLAY_PROVIDERS: Provider[] = [
   Overlay,
diff --git a/src/lib/datepicker/datepicker-animations.ts b/src/lib/datepicker/datepicker-animations.ts
@@ -14,7 +14,10 @@ import {
   AnimationTriggerMetadata,
 } from '@angular/animations';
 
-/** Animations used by the Material datepicker. */
+/**
+ * Animations used by the Material datepicker.
+ * @docs-private
+ */
 export const matDatepickerAnimations: {
   readonly transformPanel: AnimationTriggerMetadata;
   readonly fadeInCalendar: AnimationTriggerMetadata;
diff --git a/src/lib/dialog/dialog-animations.ts b/src/lib/dialog/dialog-animations.ts
@@ -26,7 +26,10 @@ const animationBody = [
       animate('75ms cubic-bezier(0.4, 0.0, 0.2, 1)', style({opacity: 0}))),
 ];
 
-/** Animations used by MatDialog. */
+/**
+ * Animations used by MatDialog.
+ * @docs-private
+ */
 export const matDialogAnimations: {
   readonly dialogContainer: AnimationTriggerMetadata;
   readonly slideDialog: AnimationTriggerMetadata;
diff --git a/src/lib/expansion/expansion-animations.ts b/src/lib/expansion/expansion-animations.ts
@@ -34,11 +34,13 @@ export const EXPANSION_PANEL_ANIMATION_TIMING = '225ms cubic-bezier(0.4,0.0,0.2,
  * `collapsed` this acts a noop since no style values change.
  *
  * In the case where angular's animation state is out of sync with the expansion panel's state, the
- * expansion panel being `expanded` and angular animations being`void`, the animation from the
+ * expansion panel being `expanded` and angular animations being `void`, the animation from the
  * `expanded`'s effective styles (though in a `void` animation state) to the collapsed state will
  * occur as expected.
  *
  * Angular Bug: https://github.com/angular/angular/issues/18847
+ *
+ * @docs-private
  */
 export const matExpansionAnimations: {
   readonly indicatorRotate: AnimationTriggerMetadata;
diff --git a/src/lib/form-field/form-field-animations.ts b/src/lib/form-field/form-field-animations.ts
@@ -14,7 +14,10 @@ import {
   AnimationTriggerMetadata,
 } from '@angular/animations';
 
-/** Animations used by the MatFormField. */
+/**
+ * Animations used by the MatFormField.
+ * @docs-private
+ */
 export const matFormFieldAnimations: {
   readonly transitionMessages: AnimationTriggerMetadata
 } = {
diff --git a/src/lib/menu/menu-animations.ts b/src/lib/menu/menu-animations.ts
@@ -21,6 +21,7 @@ import{
  * Animations used by the mat-menu component.
  * Animation duration and timing values are based on:
  * https://material.io/guidelines/components/menus.html#menus-usage
+ * @docs-private
  */
 export const matMenuAnimations: {
   readonly transformMenu: AnimationTriggerMetadata;
@@ -65,11 +66,13 @@ export const matMenuAnimations: {
 /**
  * @deprecated
  * @breaking-change 7.0.0
+ * @docs-private
  */
 export const fadeInItems = matMenuAnimations.fadeInItems;
 
 /**
  * @deprecated
  * @breaking-change 7.0.0
+ * @docs-private
  */
 export const transformMenu = matMenuAnimations.transformMenu;
diff --git a/src/lib/select/select-animations.ts b/src/lib/select/select-animations.ts
@@ -20,6 +20,7 @@ import {
  * const containing the metadata for one animation.
  *
  * The values below match the implementation of the AngularJS Material mat-select animation.
+ * @docs-private
  */
 export const matSelectAnimations: {
   readonly transformPanel: AnimationTriggerMetadata;
@@ -74,11 +75,13 @@ export const matSelectAnimations: {
 /**
  * @deprecated
  * @breaking-change 7.0.0
+ * @docs-private
  */
 export const transformPanel = matSelectAnimations.transformPanel;
 
 /**
  * @deprecated
  * @breaking-change 7.0.0
+ * @docs-private
  */
 export const fadeInContent = matSelectAnimations.fadeInContent;
diff --git a/src/lib/sidenav/drawer-animations.ts b/src/lib/sidenav/drawer-animations.ts
@@ -14,7 +14,10 @@ import {
   AnimationTriggerMetadata,
 } from '@angular/animations';
 
-/** Animations used by the Material drawers. */
+/**
+ * Animations used by the Material drawers.
+ * @docs-private
+ */
 export const matDrawerAnimations: {
   readonly transformDrawer: AnimationTriggerMetadata;
 } = {
diff --git a/src/lib/snack-bar/snack-bar-animations.ts b/src/lib/snack-bar/snack-bar-animations.ts
@@ -14,7 +14,10 @@ import {
   AnimationTriggerMetadata,
 } from '@angular/animations';
 
-/** Animations used by the Material snack bar. */
+/**
+ * Animations used by the Material snack bar.
+ * @docs-private
+ */
 export const matSnackBarAnimations: {
   readonly snackBarState: AnimationTriggerMetadata;
 } = {
diff --git a/src/lib/sort/sort-animations.ts b/src/lib/sort/sort-animations.ts
@@ -19,7 +19,10 @@ import {AnimationCurves, AnimationDurations} from '@angular/material/core';
 const SORT_ANIMATION_TRANSITION = AnimationDurations.ENTERING + ' ' +
                                   AnimationCurves.STANDARD_CURVE;
 
-/** Animations used by MatSort. */
+/**
+ * Animations used by MatSort.
+ * @docs-private
+ */
 export const matSortAnimations: {
   readonly indicator: AnimationTriggerMetadata;
   readonly leftPointer: AnimationTriggerMetadata;
diff --git a/src/lib/stepper/stepper-animations.ts b/src/lib/stepper/stepper-animations.ts
@@ -14,7 +14,10 @@ import {
   AnimationTriggerMetadata,
 } from '@angular/animations';
 
-/** Animations used by the Material steppers. */
+/**
+ * Animations used by the Material steppers.
+ * @docs-private
+ */
 export const matStepperAnimations: {
   readonly horizontalStepTransition: AnimationTriggerMetadata;
   readonly verticalStepTransition: AnimationTriggerMetadata;
diff --git a/src/lib/tabs/tabs-animations.ts b/src/lib/tabs/tabs-animations.ts
@@ -14,7 +14,10 @@ import {
   AnimationTriggerMetadata,
 } from '@angular/animations';
 
-/** Animations used by the Material tabs. */
+/**
+ * Animations used by the Material tabs.
+ * @docs-private
+ */
 export const matTabsAnimations: {
   readonly translateTab: AnimationTriggerMetadata;
 } = {
diff --git a/src/lib/tooltip/tooltip-animations.ts b/src/lib/tooltip/tooltip-animations.ts
@@ -15,7 +15,10 @@ import {
   trigger,
 } from '@angular/animations';
 
-/** Animations used by MatTooltip. */
+/**
+ * Animations used by MatTooltip.
+ * @docs-private
+ */
 export const matTooltipAnimations: {
   readonly tooltipState: AnimationTriggerMetadata;
 } = {
diff --git a/tools/dgeni/common/dgeni-definitions.ts b/tools/dgeni/common/dgeni-definitions.ts
@@ -1,6 +1,7 @@
 import {ApiDoc} from 'dgeni-packages/typescript/api-doc-types/ApiDoc';
 import {ClassExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassExportDoc';
 import {ClassLikeExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassLikeExportDoc';
+import {ConstExportDoc} from 'dgeni-packages/typescript/api-doc-types/ConstExportDoc';
 import {PropertyMemberDoc} from 'dgeni-packages/typescript/api-doc-types/PropertyMemberDoc';
 import {ParsedDecorator} from 'dgeni-packages/typescript/services/TsParser/getDecorators';
 import {FunctionExportDoc} from 'dgeni-packages/typescript/api-doc-types/FunctionExportDoc';
@@ -51,3 +52,6 @@ export interface CategorizedMethodMemberDoc
 /** Extended Dgeni function export document that simplifies logic for the Dgeni template. */
 export interface CategorizedFunctionExportDoc
     extends NormalizedFunctionDoc, FunctionExportDoc, DeprecationDoc {}
+
+/** Extended Dgeni const export document that simplifies logic for the Dgeni template. */
+export interface CategorizedConstExportDoc extends ConstExportDoc, DeprecationDoc {}
diff --git a/tools/dgeni/index.ts b/tools/dgeni/index.ts
@@ -1,5 +1,6 @@
 import {Package} from 'dgeni';
 import {Host} from 'dgeni-packages/typescript/services/ts-host/host';
+import {HighlightNunjucksExtension} from './nunjucks-tags/highlight';
 import {patchLogService} from './patch-log-service';
 import {DocsPrivateFilter} from './processors/docs-private-filter';
 import {Categorizer} from './processors/categorizer';
@@ -163,4 +164,6 @@ apiDocsPackage.config((templateFinder: any, templateEngine: any) => {
     variableStart: '{$',
     variableEnd: '$}'
   };
+
+  templateEngine.tags.push(new HighlightNunjucksExtension());
 });
diff --git a/tools/dgeni/nunjucks-tags/highlight.ts b/tools/dgeni/nunjucks-tags/highlight.ts
@@ -0,0 +1,37 @@
+const hljs = require('highlight.js');
+
+/**
+ * Nunjucks extension that supports rendering highlighted content. Content that is placed in
+ * between a {% highlight %} and {% end_highlight %} block will be automatically highlighted.
+ *
+ * HighlightJS cannot detect the code language automatically. Therefore, developers need to
+ * specify the language manually as first tag-block argument.
+ */
+export class HighlightNunjucksExtension {
+
+  /** Tags that will be parsed by this Nunjucks extension. */
+  tags = ['highlight'];
+
+  /** Disable autoescaping for content that is rendered within this extension. */
+  autoescape = false;
+
+  parse(parser: any, nodes: any) {
+    const startToken = parser.nextToken();
+    const args = parser.parseSignature(null, true);
+
+    // Jump to the end of the "{% highlight }" block.
+    parser.advanceAfterBlockEnd(startToken.value);
+
+    // Parse text content until {% end_highlight }" has been reached.
+    const textContent = parser.parseUntilBlocks('end_highlight');
+
+    // Jump to the end of the "{% highlight }" block.
+    parser.advanceAfterBlockEnd();
+
+    return new nodes.CallExtension(this, 'render', args, [textContent]);
+  }
+
+  render(_context: any, language: string, contentFn: () => string) {
+    return hljs.highlight(language, contentFn()).value;
+  }
+}
diff --git a/tools/dgeni/processors/categorizer.ts b/tools/dgeni/processors/categorizer.ts
@@ -12,6 +12,7 @@ import {
 import {
   CategorizedClassDoc,
   CategorizedClassLikeDoc,
+  CategorizedConstExportDoc,
   CategorizedFunctionExportDoc,
   CategorizedMethodMemberDoc,
   CategorizedPropertyMemberDoc,
@@ -42,6 +43,10 @@ export class Categorizer implements Processor {
     docs
       .filter(doc => doc.docType === 'function')
       .forEach(doc => this.decorateFunctionExportDoc(doc));
+
+    docs
+      .filter(doc => doc.docType === 'const')
+      .forEach(doc => this.decorateConstExportDoc(doc));
   }
 
   /**
@@ -117,6 +122,14 @@ export class Categorizer implements Processor {
     decorateDeprecatedDoc(functionDoc);
   }
 
+  /**
+   * Method that will be called for each const export document. We decorate the const
+   * documents with a property that states whether the constant is deprecated or not.
+   */
+  private decorateConstExportDoc(doc: CategorizedConstExportDoc) {
+    decorateDeprecatedDoc(doc);
+  }
+
   /**
    * Method that will be called for each property doc. Properties that are Angular inputs or
    * outputs will be marked. Aliases for the inputs or outputs will be stored as well.
diff --git a/tools/dgeni/processors/entry-point-grouper.ts b/tools/dgeni/processors/entry-point-grouper.ts
@@ -1,4 +1,5 @@
 import {DocCollection, Document, Processor} from 'dgeni';
+import {ConstExportDoc} from 'dgeni-packages/typescript/api-doc-types/ConstExportDoc';
 import {FunctionExportDoc} from 'dgeni-packages/typescript/api-doc-types/FunctionExportDoc';
 import {InterfaceExportDoc} from 'dgeni-packages/typescript/api-doc-types/InterfaceExportDoc';
 import {TypeAliasExportDoc} from 'dgeni-packages/typescript/api-doc-types/TypeAliasExportDoc';
@@ -50,6 +51,9 @@ export class EntryPointDoc {
   /** Functions that belong to the entry-point. */
   functions: FunctionExportDoc[] = [];
 
+  /** Constants that belong to the entry-point. */
+  constants: ConstExportDoc[] = [];
+
   /** NgModule that defines the current entry-point. */
   ngModule: CategorizedClassDoc | null = null;
 
@@ -108,6 +112,8 @@ export class EntryPointGrouper implements Processor {
         entryPoint.typeAliases.push(doc);
       } else if (doc.docType === 'function') {
         entryPoint.functions.push(doc);
+      } else if (doc.docType === 'const') {
+        entryPoint.constants.push(doc);
       }
     });
 
diff --git a/tools/dgeni/templates/constant.template.html b/tools/dgeni/templates/constant.template.html
@@ -0,0 +1,24 @@
+{% import "macros.html" as macros %}
+
+<h4 id="{$ constant.name $}" class="docs-header-link docs-api-h4 docs-api-constant-name">
+  <span header-link="{$ constant.name $}"></span>
+  <code>{$ constant.name $}</code>
+</h4>
+
+{%- if constant.isDeprecated -%}
+<div class="docs-api-constant-deprecated-marker" {$ macros.deprecationTitle(constant) $}>
+  Deprecated
+</div>
+{%- endif -%}
+
+{%- if constant.description -%}
+  <p class="docs-api-constant-description">{$ constant.description | marked | safe $}</p>
+{%- endif -%}
+
+<pre class="docs-markdown-pre">
+<code class="docs-markdown-code">
+{%- highlight "typescript" -%}
+  const {$ constant.name | safe $}: {$ constant.type | safe $}
+{%- end_highlight -%}
+</code>
+</pre>
diff --git a/tools/dgeni/templates/entry-point.template.html b/tools/dgeni/templates/entry-point.template.html
@@ -27,6 +27,10 @@
   {% include 'type-alias.template.html' %}
 {% endmacro %}
 
+{% macro constant(constant) -%}
+  {% include 'constant.template.html' %}
+{% endmacro %}
+
 <div class="docs-api">
   <h2>
     API reference for Angular {$ doc.packageDisplayName $} {$ doc.displayName $}
@@ -102,4 +106,14 @@ <h3 id="type_aliases" class="docs-header-link docs-api-h3">
       {$ typeAlias(item) $}
     {% endfor %}
   {%- endif -%}
+
+  {%- if doc.constants.length -%}
+    <h3 id="constants" class="docs-header-link docs-api-h3">
+      <span header-link="constants"></span>
+      Constants
+    </h3>
+    {% for item in doc.constants %}
+      {$ constant(item) $}
+    {% endfor %}
+  {%- endif -%}
 </div>
