From bd08ab2f1249ba6a947ee1756feb4f17dec471d6 Mon Sep 17 00:00:00 2001 From: Brian Mock Date: Wed, 31 Dec 2014 12:53:16 -0800 Subject: [PATCH] Switch to Handelbars; generate from JSDocs --- .gitignore | 3 +- doc.yaml | 82 ------------------- docs/main.js | 19 ++--- .../docs.html.handlebars | 69 +++++++--------- .../index.html.handlebars | 12 ++- jsdoc-template/publish.js | 50 +++++++++-- less/hljs.less | 11 +++ less/layout.less | 59 ++++++++----- less/sidebar.less | 10 ++- package.json | 1 + 10 files changed, 151 insertions(+), 165 deletions(-) delete mode 100644 doc.yaml rename docs/index.html => jsdoc-template/docs.html.handlebars (59%) rename index.html => jsdoc-template/index.html.handlebars (67%) diff --git a/.gitignore b/.gitignore index 51b178cc9..c56c58984 100644 --- 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 deleted file mode 100644 index d6c8921bc..000000000 --- a/doc.yaml +++ /dev/null @@ -1,82 +0,0 @@ -- name: all - category: List - sig: "(a -> Boolean) -> [a] -> Boolean" - params: - - name: fn - type: Function - description: The predicate function. - - name: list - type: Array - description: The array to consider. - returns: - type: Boolean - description: | - `true` if the predicate is satisfied by every element, `false` otherwise - description: | - Returns `true` if all elements of the list match the predicate, `false` if - there are any that don't. - example: | - var lessThan2 = R.flip(R.lt)(2); - var lessThan3 = R.flip(R.lt)(3); - var xs = R.range(1, 3); - xs; //=> [1, 2] - R.all(lessThan2)(xs); //=> false - R.all(lessThan3)(xs); //=> true -- name: foldl - category: List - sig: "(a, b -> a) -> a -> [b] -> a" - params: - - name: fn - type: Function - description: | - The iterator function. Receives two values, the accumulator and the - current element from the array. - - name: acc - type: any - description: The accumulator value. - - name: list - type: Array - description: The list to iterate over. - returns: - type: any - description: The final, accumulated value. - example: | - var numbers = [1, 2, 3]; - var add = function(a, b) { - return a + b; - }; - - R.foldl(add, 10, numbers); //=> 16 - description: | - Returns a single item by iterating through the list, successively calling - the iterator function and passing it an accumulator value and the current - value from the array, and then passing the result to the next call. - - The iterator function receives two values: *(acc, value)* - - Note: `R.foldl` does not skip deleted or unassigned indices (sparse arrays), - unlike the native `Array.prototype.reduce` method. For more details on this - behavior, see [the MDN page on Array.reduce](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce#Description). -- name: prop - category: Object - sig: "s -> {s: a} -> a" - params: - - name: p - type: String - description: The property name - - name: obj - type: Object - description: The object to query - returns: - type: any - description: The value at `obj.p` - description: | - Returns a function that when supplied an object returns the indicated - property of that object, if it exists. - example: | - R.prop('x', {x: 100}); //=> 100 - R.prop('x', {}); //=> undefined - - var fifth = R.prop(4); - var dwarfs = ['Bashful', 'Doc', 'Dopey', 'Grumpy', 'Happy', 'Sleepy', 'Sneezy']; - fifth(dwarfs); //=> 'Happy' diff --git a/docs/main.js b/docs/main.js index 772c1db00..852737923 100644 --- 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 b/jsdoc-template/docs.html.handlebars similarity index 59% rename from docs/index.html rename to jsdoc-template/docs.html.handlebars index b825f8646..7f918e239 100644 --- a/docs/index.html +++ b/jsdoc-template/docs.html.handlebars @@ -1,5 +1,5 @@ - + @@ -14,7 +14,7 @@
Ramda - v0.8.0 + v{{version}}
@@ -47,69 +47,62 @@
- + {{#each docs}}

- - + {{name}} + {{category}}

-
+ {{#if sig}} +
+ {{/if}} -
+

Parameters

    - + {{#each params}}
  • - - - + {{type}} + {{name}} + {{{description}}}
    • - + {{/each}}

Returns

- + {{#with returns}}
- - + {{type}} + {{{description}}}
- + {{/with}}
-
+
{{{description}}}
- + {{#if see}}
- See also - . + See also {{see}}.
- + {{/if}} - -
- + {{#if example}} + 
{{{example}}}
+ {{/if}}
- + {{/each}}
+ diff --git a/index.html b/jsdoc-template/index.html.handlebars similarity index 67% rename from index.html rename to jsdoc-template/index.html.handlebars index c1dc89162..884192c6a 100644 --- a/index.html +++ b/jsdoc-template/index.html.handlebars @@ -1,11 +1,9 @@ - + - Ramda JS - - + Ramda Documentation @@ -13,7 +11,7 @@
Ramda - v0.8.0 + v{{version}}
@@ -23,8 +21,8 @@
-
- TODO: PAGE INFORMATION +
+
{{> readme}}
diff --git a/jsdoc-template/publish.js b/jsdoc-template/publish.js index b4d3e6ecc..78edb9c35 100644 --- 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 index 93af5d957..774f1fd05 100644 --- 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; +} diff --git a/less/layout.less b/less/layout.less index 5f058b416..f91de2763 100644 --- a/less/layout.less +++ b/less/layout.less @@ -1,34 +1,55 @@ @padding: 15px; @sidebar-width: 250px; -main, -header, -aside { - position: fixed; +.main-content() { + top: @navbar-height; + right: 0; + bottom: 0; + overflow: auto; + padding-top: @padding; } header { + position: fixed; width: 100%; top: 0; right: 0; } -aside { - left: 0; - top: @navbar-height; - bottom: 0; - width: @sidebar-width; -} +html.docs-page { + aside { + position: fixed; + left: 0; + top: @navbar-height; + bottom: 0; + width: @sidebar-width; + } -main.container-fluid { - left: @sidebar-width; - top: @navbar-height; - right: 0; - bottom: 0; - padding-top: @padding; - overflow: auto; + main { + .main-content(); + position: fixed; + left: @sidebar-width; + } + + body { + background: #eee; + } } -body { - background: #eee; +html.home-page { + body { + .main-content(); + position: relative; + left: 0; + background: #eee; + margin: @padding; + margin-top: 0; + } + + main { + background: #fff; + border: 1px solid white; + box-shadow: 0 0 0 1px #ccc; + border-radius: @border-radius-base; + } } diff --git a/less/sidebar.less b/less/sidebar.less index e3d0fa6ab..94c51ca90 100644 --- a/less/sidebar.less +++ b/less/sidebar.less @@ -12,19 +12,23 @@ } .toc { - margin: 0 -15px; + @padding: 5px; + @margin: 15px; + + margin: 0 (-@margin); width: 100%; bottom: 0; top: 60px; background: #f8f8f8; border-top: @border; position: absolute; - padding-top: 5px; + + padding: (3 * @padding) 0; overflow: auto; a { - padding: 4px 15px; + padding: @padding @margin; border-radius: 0; &:hover { diff --git a/package.json b/package.json index 403e0ba2f..665190ebb 100644 --- a/package.json +++ b/package.json @@ -57,6 +57,7 @@ "grunt-mocha": "~0.4.11", "grunt-mocha-test": "~0.11.0", "grunt-saucelabs": "^8.3.1", + "handlebars": "^2.0.0", "highlight.js": "^8.4.0", "js-yaml": "^3.2.5", "lodash": "latest",