Update API Docs

tafsiri · web-flow · commit 82076327a7ab · 2018-02-14T11:07:40.000-05:00
* add syntax highlighting to code samples.
* style subsection descriptions
* add dl library to page
* fix markdown rendering of table in norm docs.
diff --git a/package.json b/package.json
@@ -22,6 +22,7 @@
     "cross-spawn": "~5.1.0",
     "fetch-mock": "~5.13.1",
     "handlebars": "~4.0.11",
+    "highlight.js": "9.12.0",
     "http-server": "~0.10.0",
     "jasmine-core": "~2.6.4",
     "karma": "~1.7.0",
diff --git a/src/ops/norm.ts b/src/ops/norm.ts
@@ -32,16 +32,16 @@ export class Ops {
    * @param x The input array.
    * @param ord Optional. Order of the norm. Supported norm types are
    * following:
-   * ```
-   *     ord         norm for matrices          norm for vectors
-   *     -------------------------------------------------------
-   *     'euclidean' Frobenius norm             2-norm
-   *     ‘fro’       Frobenius norm	            –
-   *     Infinity    max(sum(abs(x), axis=1))   max(abs(x))
-   *     -Infinity   min(sum(abs(x), axis=1))   min(abs(x))
-   *     1           max(sum(abs(x), axis=0))   sum(abs(x))
-   *     2           -                          sum(abs(x)^2)^1/2*
-   * ```
+   *
+   *  | ord        | norm for matrices         | norm for vectors
+   *  |------------|---------------------------|---------------------
+   *  |'euclidean' |Frobenius norm             |2-norm
+   *  |'fro'       |Frobenius norm	           |
+   *  |Infinity    |max(sum(abs(x), axis=1))   |max(abs(x))
+   *  |-Infinity   |min(sum(abs(x), axis=1))   |min(abs(x))
+   *  |1           |max(sum(abs(x), axis=0))   |sum(abs(x))
+   *  |2           |                           |sum(abs(x)^2)^1/2*
+   *
    *
    * @param axis Optional. If axis is null (the default), the input is
    * considered a vector and a single vector norm is computed over the entire
diff --git a/website/api/index.html b/website/api/index.html
@@ -1,6 +1,7 @@
 <head>
-  <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:300,400,500,700" type="text/css">
+  <script src="https://cdn.jsdelivr.net/npm/deeplearn@latest"></script>
   <link rel="stylesheet" href="https://code.getmdl.io/1.3.0/material.cyan-teal.min.css" />
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.css">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
   <style>
@@ -15,6 +16,26 @@
       color: inherit;
     }
 
+    table {
+      text-align: left;
+      font-family: "Roboto Mono", monospace;
+    }
+
+    thead {
+      background-color: #dedede;
+    }
+
+    th {
+      text-align: left;
+      padding: 4px;
+    }
+
+    td {
+      text-align: left;
+      padding: 8px;
+      padding-right: 16px;
+    }
+
     .container {
       display: flex;
       flex-direction: column;
@@ -131,22 +152,48 @@
     }
 
     .reference .subsection-title {
-      font-weight: 200;
-      margin-bottom: 80px;
+      font-weight: 300;
+      margin-bottom: 16px;
+      /* border-bottom: 1px solid rgb(96,125,139); */
+    }
+
+    .reference .subsection-description {
+      font-weight: 300;
+      margin-bottom: 96px;
       border-bottom: 1px solid rgb(96,125,139);
+      margin-left: 8px;
+    }
+
+    .reference .symbol-marker {
+      display: inline-block;
+      margin-right: 12px;
+      font-style: italic;
+      font-size: 90%;
+      color: grey;
     }
 
     .documentation pre, .param-docs pre {
       background: #f4f4f4;
     }
 
+    code.hljs {
+      border-radius: 5px;
+      padding-left: 16px;
+    }
+
+    pre.hljs {
+      margin: 0;
+      padding: 0;
+    }
+
+
+
     code, .param-name, .return-type {
+      background: #f7f7f7;
       background: #f4f4f4;
       color: #37474f;
       padding: 2px 4px;
       font: 500 90%/2 Roboto Mono, monospace;
-    }
-    code {
       word-break: break-word;
     }
 
@@ -162,9 +209,9 @@
 
     .reference .symbol {
       margin-left: 32px;
-      margin-bottom: 80px;
+      margin-bottom: 96px;
       border-bottom: 1px dashed lightgrey;
-      padding-bottom: 50px;
+      padding-bottom: 16px;
     }
 
     .reference .symbol .documentation p {
@@ -256,10 +303,11 @@
           {{#subheadings}}
           <div class="subsection">
             <div class="subsection-title mdl-typography--display-3">{{../name}} &nbsp;/&nbsp; {{name}}</div>
-            <div class="subheading-description">{{description}}</div>
+            <div class="subsection-description mdl-typography--headline">{{{description}}}</div>
             {{#symbols}}
             <div class="symbol">
-              <h5>#
+              <h5>
+                <span class='symbol-marker'>&fnof;</span>
                 <a name="{{urlHash}}" href="#{{urlHash}}">{{displayName}}</a>{{paramStr}}
                 {{#isClass}}
                   <span class="class-chip mdl-chip">
diff --git a/website/scripts/api-parser.ts b/website/scripts/api-parser.ts
@@ -46,13 +46,17 @@ export function parse():
   const docHeadings: DocHeading[] = [
     {
       name: 'Tensors',
-      description: `Tensors are the core datastructure of deeplearn.js. ` +
-          `They are a generalization of vectors and matrices to potentially ` +
-          `higher dimensions.`,
+      description: '',
       subheadings: [
         {
           name: 'Creation',
-          description: `This section describes how to construct tensors.`,
+          description: `Tensors are the core datastructure of deeplearn.js.
+             They are a generalization of vectors and matrices to potentially
+             higher dimensions.
+             <br><br>
+             We have utility functions for common cases like 1D, 2D, 3D
+             and 4D tensors, as well a number of functions to iniatialize
+             tensors in ways useful for machine learning`,
           pin: [
             'tensor', 'scalar', 'tensor1d', 'tensor2d', 'tensor3d', 'tensor4d'
           ]
diff --git a/website/scripts/make-api.ts b/website/scripts/make-api.ts
@@ -22,6 +22,7 @@
 
 import * as fs from 'fs';
 import * as HandleBars from 'handlebars';
+import * as hljs from 'highlight.js';
 import * as MarkdownIt from 'markdown-it';
 import * as minimist from 'minimist';
 import * as mkdirp from 'mkdirp';
@@ -70,19 +71,33 @@ const symbols: util.SymbolAndUrl[] = [
 ];
 util.linkSymbols(docs, symbols, TOPLEVEL_NAMESPACE, docLinkAliases);
 
-const md = new MarkdownIt();
+const md = new MarkdownIt({
+  highlight(str, lang) {
+    if (lang === 'js' && hljs.getLanguage(lang)) {
+      const highlighted = hljs.highlight(lang, str).value;
+      return '<pre class="hljs"><code class="hljs language-js">' + highlighted +
+          '</code></pre>\n';
+    }
+
+    return '';  // use external default escaping
+  }
+});
 
 // Add some helper functions
 HandleBars.registerHelper('markdown', attr => {
-  return md.render(attr);
+  if (attr) {
+    return md.render(attr);
+  }
 });
 
 // Renders a string to markdown but removes the outer <p> tag
 HandleBars.registerHelper('markdownInner', attr => {
-  const asMd =
-      md.render(attr.trim()).replace(/<p>/, '').replace(/(<\/p>\s*)$/, '');
+  if (attr) {
+    const asMd =
+        md.render(attr.trim()).replace(/<p>/, '').replace(/(<\/p>\s*)$/, '');
 
-  return asMd;
+    return asMd;
+  }
 });
 
 // Write the HTML.
diff --git a/yarn.lock b/yarn.lock
@@ -1618,7 +1618,7 @@ he@^1.1.1:
   version "1.1.1"
   resolved "https://registry.yarnpkg.com/he/-/he-1.1.1.tgz#93410fd21b009735151f8868c2f271f3427e23fd"
 
-highlight.js@^9.0.0:
+highlight.js@9.12.0, highlight.js@^9.0.0:
   version "9.12.0"
   resolved "https://registry.yarnpkg.com/highlight.js/-/highlight.js-9.12.0.tgz#e6d9dbe57cbefe60751f02af336195870c90c01e"
 
