Runnable code snippets in API reference. (#719)

Let there be runnable snippets!

Author: Nikhil Thorat

src/ops/array_ops.ts

@@ -228,6 +228,10 @@ export class Ops {
   /**
    * Creates a `Tensor` with all elements set to 1.
    *
+   * ```js
+   * dl.ones([2, 2]).print();
+   * ```
+   *
    * @param shape An array of integers defining the output tensor shape.
    * @param dtype The type of an element in the resulting tensor. Defaults to
    *     'float'.
@@ -242,6 +246,11 @@ export class Ops {
 
   /**
    * Creates a `Tensor` with all elements set to 0.
+   *
+   * ```js
+   * dl.zeros([2, 2]).print();
+   * ```
+   *
    * @param shape An array of integers defining the output tensor shape.
    * @param dtype The type of an element in the resulting tensor. Can
    *     be 'float32', 'int32' or 'bool'. Defaults to 'float'.
@@ -257,6 +266,10 @@ export class Ops {
   /**
    * Creates a `Tensor` filled with a scalar value.
    *
+   * ```js
+   * dl.fill([2, 2], 4).print();
+   * ```
+   *
    * @param shape An array of integers defining the output tensor shape.
    * @param value The scalar value to fill the tensor with.
    * @param dtype The type of an element in the resulting tensor. Defaults to
@@ -276,6 +289,11 @@ export class Ops {
   /**
    * Creates a `Tensor` with all elements set to 1 with the same shape as the
    * given tensor.
+   *
+   * ```js
+   * const x = dl.tensor([1, 2]);
+   * dl.onesLike(x).print();
+   * ```
    * @param x A tensor.
    */
   @doc({heading: 'Tensors', subheading: 'Creation'})
@@ -288,6 +306,11 @@ export class Ops {
    * Creates a `Tensor` with all elements set to 0 with the same shape as the
    * given tensor.
    *
+   * ```js
+   * const x = dl.tensor([1, 2]);
+   * dl.zerosLike(x).print();
+   * ```
+   *
    * @param x A tensor.
    */
   @doc({heading: 'Tensors', subheading: 'Creation'})
@@ -299,6 +322,12 @@ export class Ops {
   /**
    * Creates a new tensor with the same values and shape as the specified
    * tensor.
+   *
+   * ```js
+   * const x = dl.tensor([1, 2]);
+   * x.clone().print();
+   * ```
+   *
    * @param x The tensor to clone.
    */
   @doc({heading: 'Tensors', subheading: 'Creation'})
@@ -413,6 +442,11 @@ export class Ops {
   /**
    * Creates a `Tensor` with values drawn from a multinomial distribution.
    *
+   * ```js
+   * const probs = dl.tensor([.75, .25]);
+   * dl.multinomial(probs, 3).print();
+   * ```
+   *
    * @param probabilities 1D array with normalized outcome probabilities, or
    *     2D array of shape `[batchSize, numOutcomes]`.
    * @param numSamples Number of samples to draw for each row slice.
@@ -719,6 +753,9 @@ export class Ops {
   /**
    * Return an evenly spaced sequence of numbers over the given interval.
    *
+   * ```js
+   * dl.linspace(0, 9, 10).print();
+   * ```
    * @param start The start value of the sequence
    * @param stop The end value of the sequence
    * @param num The number of values to generate
@@ -797,6 +834,19 @@ export class Ops {
    * `buffer.set()`, or by modifying directly `buffer.values`. When done,
    * call `buffer.toTensor()` to get an immutable `Tensor` with those values.
    *
+   * When done, call `buffer.toTensor()` to get an immutable `Tensor` with those
+   * values.
+   *
+   * ```js
+   * // Create a buffer and set values at particular indices.
+   * const buffer = dl.buffer([2, 2]);
+   * buffer.set(3, 0, 0);
+   * buffer.set(5, 1, 0);
+   *
+   * // Convert the buffer back to a tensor.
+   * buffer.toTensor().print();
+   * ```
+   *
    * @param shape An array of integers defining the output tensor shape.
    * @param dtype The dtype of the buffer. Defaults to 'float32'.
    * @param values The values of the buffer as `TypedArray`. Defaults to zeros.
@@ -816,20 +866,22 @@ export class Ops {
    */
   @doc({heading: 'Tensors', subheading: 'Creation'})
   static print<T extends Tensor>(x: T, verbose = false): void {
-    let displayName = Tensor.name;
-    if (x.rank <= 4) {
-      displayName =
-          ['Scalar', 'Tensor1D', 'Tensor2D', 'Tensor3D', 'Tensor4D'][x.rank];
-    }
-
-    // Construct a new class so that we can display a rich object in the console
-    // that only has the properties that we want to show about the tensor but
-    // still shows it as if it's the proper class.
-    const C = new Function(`return class ${displayName} {}`)();
+    const C = class Tensor {
+      shape: number[];
+      data: number[];
+      dtype: string;
+      size: number;
+    };
 
     const displayTensor = new C();
     displayTensor.shape = x.shape;
     displayTensor.data = Array.from(x.dataSync());
+    displayTensor.toString = function() {
+      return `Tensor {\n` +
+          `  data: [${this.data.join(', ')}],\n` +
+          `  shape: [${x.shape.join(', ')}]\n` +
+          `}`;
+    };
 
     if (verbose) {
       displayTensor.dtype = x.dtype;

src/ops/binary_ops.ts

@@ -137,7 +137,7 @@ export class Ops {
    *
    * ```js
    * const a = dl.tensor([[2, 2], [3, 3]])
-   * const b = dl.tensor([[8, 16], [2, 3]])
+   * const b = dl.tensor([[8, 16], [2, 3]]).toInt()
    * dl.pow(a, b).print();  // [256, 65536, 9, 27]
    * ```
    *

website/api/index.html

@@ -1,5 +1,5 @@
 <head>
-  <script src="https://cdn.jsdelivr.net/npm/deeplearn@latest"></script>
+  <script src="{{bundleJsPath}}"></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/railscasts.min.css">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -195,7 +195,7 @@
       margin-right: 0.33em;
     }
 
-    .documentation pre, .param-docs pre {
+    .param-docs pre {
       background: #f4f4f4;
     }
 
@@ -205,9 +205,11 @@
     }
 
     pre.hljs {
-      margin: 24px;
+      padding: 24px;
+      padding-bottom: 32px;
       /* margin-left: 24px; */
-      padding: 0;
+      margin: 0;
+      background: white;
     }
 
     code, .param-name, .return-type {
@@ -228,8 +230,6 @@
       font-family: Roboto Mono, monospace;
     }
 
-
-
     .reference .symbol {
       margin-left: 32px;
       margin-bottom: 96px;
@@ -287,6 +287,26 @@
       font-size: 82%;
     }
 
+    .snippet-console {
+      margin: -32px 24px 0 24px;
+      min-height: 24px;
+      position: relative;
+    }
+
+    .snippet-console-log {
+      border-radius: 8px;
+      background: #f4f4f4;
+      padding: 8px 16px;
+      min-height: 16px;
+      white-space: pre;
+      font-family: "Roboto Mono", monospace;
+    }
+
+    .snippet-run-button {
+      position: absolute;
+      right: 4px;
+      top: 4px;
+    }
   </style>
 
   <script>
@@ -389,7 +409,6 @@
         {{/headings}}
       </div>
 
-
       <div class="reference">
         {{#headings}}
         <div class="section">
@@ -449,4 +468,49 @@ <h6>Methods:</h6>
       </div>
     </div>
   </div>
+  <script>
+    function executeCodeSnippet(consoleLogElement, codeSnippet) {
+      consoleLogElement.innerText = '';
+
+      var oldLog = console.log;
+      console.log = function(logStr) {
+        consoleLogElement.innerText += logStr + '\n';
+      };
+
+      var snippet = 'dl.tidy(function() {' + codeSnippet + '});';
+
+      eval(snippet);
+
+      console.log = oldLog;
+    };
+
+    (function() {
+      // Find all the code blocks.
+      var jsBlocks = document.querySelectorAll('.language-js');
+      for (var i = 0; i < jsBlocks.length; i++) {
+        var block = jsBlocks[i];
+
+        var consoleElement = document.createElement('div');
+        consoleElement.className = 'snippet-console';
+
+        var consoleRunElement = document.createElement('button');
+        consoleRunElement.innerText = 'Run';
+        consoleRunElement.className = 'snippet-run-button';
+
+        var consoleLogElement = document.createElement('div');
+        consoleLogElement.className = 'snippet-console-log';
+
+        consoleElement.appendChild(consoleLogElement);
+        consoleElement.appendChild(consoleRunElement);
+        block.parentElement.insertAdjacentElement('afterend', consoleElement);
+
+        consoleRunElement.addEventListener('click', function() {
+          var consoleLogElement =
+              this.parentElement.querySelector('.snippet-console-log');
+          var snippetText = this.parentElement.previousElementSibling.innerText;
+          executeCodeSnippet(consoleLogElement, snippetText);
+        });
+      }
+    })();
+  </script>
 </body>

website/api/view.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  * =============================================================================
  */
-export interface Docs { headings: DocHeading[]; }
+export interface Docs { headings: DocHeading[]; bundleJsPath: string;}
 
 export interface DocHeading {
   name: string;

website/scripts/make-api.ts

@@ -36,9 +36,28 @@ const TOPLEVEL_NAMESPACE = 'dl';
 const API_TEMPLATE_PATH = './website/api/index.html';
 const HTML_OUT_DIR = '/tmp/deeplearn-new-website/api/';
 
+const argv = minimist(process.argv.slice(2));
+
 shell.mkdir('-p', HTML_OUT_DIR);
 
+let bundleJsPath;
+if (argv['master']) {
+  // When using --master, build a deeplearn.js bundle if it doesn't exist. This
+  // is mainly for development.
+  if (!fs.existsSync(HTML_OUT_DIR + 'deeplearn.js')) {
+    shell.exec('./scripts/build-standalone.sh');
+    shell.cp('./dist/deeplearn.js', HTML_OUT_DIR);
+  }
+  bundleJsPath = 'deeplearn.js';
+} else {
+  // Read version and point to it.
+  const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+  bundleJsPath = `https://cdn.jsdelivr.net/npm/deeplearn@${pkg.version}`;
+}
+console.log(`Using bundle path ${bundleJsPath}.`);
+
 const {docs, docLinkAliases} = parser.parse();
+docs.bundleJsPath = bundleJsPath;
 
 // Predefine some custom type links.
 const symbols: util.SymbolAndUrl[] = [