Switch to Handelbars; generate from JSDocs

tomwhale · Jan 2, 2015 · bd08ab2 · bd08ab2
1 parent 3062d49
commit bd08ab2
Show file tree

Hide file tree

Showing 10 changed files with 151 additions and 165 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,4 +6,5 @@
 /test/bundle.js
 /bower_components/
 /style.css
-/docs/data.json
+/docs/index.html
+/index.html
diff --git a/doc.yaml b/doc.yaml
diff --git a/docs/main.js b/docs/main.js
@@ -1,19 +1,18 @@
 console.time('load');
 var root = {};
 root.filter = ko.observable('');
-root.docs = ko.observableArray();
+root.docs = this.DOC_DATA || {};
 root.filteredDocs = ko.computed(function() {
-    return root.docs().filter(function(d) {
-        var filter = root.filter().toLowerCase();
-        return d.name.toLowerCase().indexOf(filter) >= 0 ||
-            d.category.toLowerCase() === filter;
+    return root.docs.filter(function(d) {
+        return strIn(root.filter(), d.name);
     });
 });
 
-function start(data) {
-    root.docs(data);
-    ko.applyBindings(root);
-    console.timeEnd('load');
+function strIn(a, b) {
+    a = a.toLowerCase();
+    b = b.toLowerCase();
+    return b.indexOf(a) >= 0;
 }
 
-$.getJSON('data.json').then(start);
+ko.applyBindings(root);
+console.timeEnd('load');
diff --git a/docs/index.html → jsdoc-template/docs.html.handlebars b/docs/index.html → jsdoc-template/docs.html.handlebars
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html>
+<html class="docs-page">
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -14,7 +14,7 @@
         <div class="navbar-header">
             <a class="navbar-brand" href="/">
                 <strong>Ramda</strong>
-                <span class="version">v0.8.0</span>
+                <span class="version">v{{version}}</span>
             </a>
         </div>
         <div class="navbar-left">
@@ -47,69 +47,62 @@
         </ul>
     </aside>
     <main class="container-fluid">
-        <!-- ko foreach: docs -->
+        {{#each docs}}
         <section class="card">
             <h2>
-                <a class="name"
-                   data-bind="
-                       attr: {
-                           href: '#' + name,
-                           id: name
-                       },
-                       text: name
-                    "
-                ></a>
-                <span
-                    class="label label-primary"
-                    data-bind="text: category"
-                ></span>
+                <a class="name" href="#{{name}}" id="{{name}}">{{name}}</a>
+                <span class="label label-primary">{{category}}</span>
             </h2>
-            <div data-bind="if: sig.length">
+            {{#if sig}}
+            <div>
                 <button data-toggle="collapse"
                         class="sig btn btn-link"
-                        data-bind="attr: { 'data-target': '#_details_' + name }"
+                        data-target="#_details_{{name}}"
                 >
                     <span class="caret"></span>
-                    <span data-bind="text: sig"></span>
+                    {{sig}}
                 </button>
             </div>
+            {{/if}}
 
-            <div class="collapse details" data-bind="attr: { id: '_details_' + name }">
+            <div class="collapse details" id="_details_{{name}}">
                 <h3>Parameters</h3>
                 <ul class="params">
-                    <!-- ko foreach: params -->
+                    {{#each params}}
                     <li class="param">
-                        <span class="type" data-bind="text: type"></span>
-                        <span class="name" data-bind="text: name"></span>
-                        <span class="description" data-bind="html: description"></span>
+                        <span class="type">{{type}}</span>
+                        <span class="name">{{name}}</span>
+                        <span class="description">{{{description}}}</span>
                     </li>
-                    <!-- /ko -->
+                    {{/each}}
                 </ul>
 
                 <h3>Returns</h3>
-                <!-- ko with: returns -->
+                {{#with returns}}
                 <div class="returns">
-                    <span class="type" data-bind="text: type"></span>
-                    <span class="description" data-bind="html: description"></span>
+                    <span class="type">{{type}}</span>
+                    <span class="description">{{{description}}}</span>
                 </div>
-                <!-- /ko -->
+                {{/with}}
             </div>
 
-            <div class="description" data-bind="html: description"></div>
+            <div class="description">{{{description}}}</div>
 
-            <!-- ko if: see.length -->
+            {{#if see}}
             <div class="see">
-                See also
-                <a data-bind="attr: { href: '#' + see }, text: see"></a>.
+                See also <a href="#{{see}}">{{see}}</a>.
             </div>
-            <!-- /ko -->
+            {{/if}}
 
-            <!-- ko if: example.length -->
-            <pre><code class="hljs javascript" data-bind="html: example"></code></pre>
-            <!-- /ko -->
+            {{#if example}}
+            <pre><code class="hljs javascript">{{{example}}}</code></pre>
+            {{/if}}
         </section>
-        <!-- /ko -->
+        {{/each}}
     </main>
+    <script>
+        var DOC_DATA = {{json data}};
+    </script>
     <script src="main.js"></script>
 </body>
 </html>
diff --git a/index.html → jsdoc-template/index.html.handlebars b/index.html → jsdoc-template/index.html.handlebars
@@ -1,19 +1,17 @@
 <!DOCTYPE html>
-<html>
+<html class="home-page">
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Ramda JS</title>
-    <script src="https://code.jquery.com/jquery-2.1.3.min.js"></script>
-    <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/js/bootstrap.min.js"></script>
+    <title>Ramda Documentation</title>
     <link rel="stylesheet" href="/style.css">
 </head>
 <body>
     <header class="navbar navbar-fixed-top navbar-inverse container-fluid">
         <div class="navbar-header">
             <a class="navbar-brand" href="/">
                 <strong>Ramda</strong>
-                <span class="version">v0.8.0</span>
+                <span class="version">v{{version}}</span>
             </a>
         </div>
         <div class="navbar-left">
@@ -23,8 +21,8 @@
             </ul>
         </div>
     </header>
-    <main class="container-fluid">
-        TODO: PAGE INFORMATION
+    <main class="container">
+        <article>{{> readme}}</article>
     </main>
 </body>
 </html>
diff --git a/jsdoc-template/publish.js b/jsdoc-template/publish.js
@@ -3,6 +3,7 @@ var helper = require('jsdoc/util/templateHelper');
 
 var marked = require('marked');
 var hljs = require('highlight.js');
+var Handlebars = require('handlebars');
 
 var R = require('../dist/ramda');
 
@@ -28,8 +29,8 @@ var prettifySig = R.pipe(
 );
 
 var prettifyCode = R.pipe(
-    R.map(trimCode),
     R.join('\n'),
+    trimCode,
     R.lPartial(hljs.highlight, 'javascript'),
     R.prop('value')
 );
@@ -61,15 +62,54 @@ function simplifyData(d) {
     };
 }
 
+function embedData(d) {
+    return {
+        name: d.name,
+        category: d.category
+    };
+}
+
+// For embedding a JSON blob with documentation data inside the HTML.
+Handlebars.registerHelper('json', function(obj) {
+    var json = JSON.stringify(obj);
+    return new Handlebars.SafeString(json);
+});
+
+// For embedding README.md as the main page.
+Handlebars.registerPartial('readme', function(obj) {
+    return new Handlebars.SafeString(readme);
+});
+
+var readFile = R.rPartial(fs.readFileSync, 'utf-8');
+var writeFile = R.rPartial(fs.writeFileSync, 'utf-8');
+
+var loadTemplate = R.pipe(readFile, Handlebars.compile);
+var loadJson = R.pipe(readFile, JSON.parse);
+var loadMarkdown = R.pipe(readFile, marked);
+
+var docTmpl = loadTemplate('jsdoc-template/docs.html.handlebars');
+var indexTmpl = loadTemplate('jsdoc-template/index.html.handlebars');
+
+var pkg = loadJson('package.json');
+var readme = loadMarkdown('README.md');
+
 function publish(data, opts, tutorials) {
     data = helper.prune(data);
-    var obj = data()
+    var fullData = data()
         .order('name, version, since')
         .filter({ kind: 'function' })
         .map(simplifyData);
-    var json = JSON.stringify(obj);
-    var filename = 'docs/data.json';
-    fs.writeFileSync(filename, json, 'utf-8');
+    var embeddedData = fullData.map(embedData);
+    var docHtml = docTmpl({
+        version: pkg.version,
+        data: embeddedData,
+        docs: fullData
+    });
+    var indexHtml = indexTmpl({
+        version: pkg.version
+    });
+    writeFile('docs/index.html', docHtml);
+    writeFile('index.html', indexHtml);
     console.log('Finished writing documentation data to docs/data.json');
 }
 

diff --git a/less/hljs.less b/less/hljs.less
@@ -8,12 +8,23 @@
     font-weight: bold;
 }
 
+.hljs-regexp,
 .hljs-string,
 .hljs-number {
     color: #fa8;
 }
 
+pre,
 .hljs {
     background: darken(@brand-primary, 15%);
     color: darken(@brand-primary, -45%);
 }
+
+pre {
+    border: 0;
+    border-radius: 0;
+    margin-left: -15px;
+    margin-right: -15px;
+    padding-left: 15px;
+    padding-right: 15px;
+}