From 5b868c60dbbb024f97f6cf0086cb50520a0ca33c Mon Sep 17 00:00:00 2001 From: brettlangdon Date: Wed, 18 Mar 2015 08:53:22 -0400 Subject: [PATCH] add documentation generation --- docs/create.js | 109 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/styles.css | 49 ++++++++++++++++++++++ package.json | 8 +++- 3 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 docs/create.js create mode 100644 docs/styles.css diff --git a/docs/create.js b/docs/create.js new file mode 100644 index 0000000..2e0df72 --- /dev/null +++ b/docs/create.js @@ -0,0 +1,109 @@ +var path = require("path"); + +var docast = require("docast"); +var glob = require("glob"); +var marked = require("marked"); +var yaml = require("js-yaml"); + +marked.setOptions({ + gfm: true, + sanitize: true, + pedantic: false +}); + +var above = path.resolve(__dirname, "../lib/"); +var match = above + "/**/*.js"; + +var docs = {}; +glob(match, function(er, files){ + files.forEach(function(file){ + var comments = docast.parse(file); + for(var i = 0; i < comments.length; ++i){ + var comment = comments[i]; + try{ + comment.doc = yaml.safeLoad(comment.doc); + if(!comment.doc.hasOwnProperty("section")){ + continue; + } + if(!docs[comment.doc.section]){ + docs[comment.doc.section] = {}; + } + + for(var key in comment.doc.params){ + if(comment.doc.params.hasOwnProperty(key)){ + comment.doc.params[key] = comment.doc.params[key].replace("optional", "_optional_"); + comment.doc.params[key] = marked(comment.doc.params[key]); + } + } + if(comment.doc.hasOwnProperty("example")){ + comment.doc.example = marked(comment.doc.example); + } else { + comment.doc.example = ""; + } + + if(comment.doc.hasOwnProperty("comment")){ + comment.doc.comment = marked(comment.doc.comment); + } else { + comment.doc.comment = ""; + } + + docs[comment.doc.section][comment.name] = comment.doc; + } catch(e){} + } + }); + + var output = "\n\n\n\n\n\n\n\n\n"; + output += "\n"; + + for(var section in docs){ + if(!docs.hasOwnProperty(section)){ + continue; + } + methods = docs[section]; + + output += "
\n"; + output += "

" + section + "

\n"; + for(var name in methods){ + if(!methods.hasOwnProperty(name)){ + continue; + } + doc = methods[name]; + + var className = section + "-" + name; + output += "
\n"; + + output += "

" + name + "

\n"; + output += "
\n"; + output += "
\n"; + output += doc.comment; + output += "

Parameters:

\n"; + for(var param in doc.params){ + if(!doc.params.hasOwnProperty(param)){ + continue; + } + var comment = doc.params[param]; + output += "
" + param + "
\n"; + output += comment; + } + output += "
\n"; + + output += "
\n"; + output += doc.example; + output += "
\n"; + + output += "
\n"; + output += "
\n"; + + } + output += "
\n"; + } + output += ""; + console.log(output); +}); diff --git a/docs/styles.css b/docs/styles.css new file mode 100644 index 0000000..e758e2c --- /dev/null +++ b/docs/styles.css @@ -0,0 +1,49 @@ + +h2 { + width: 100%; + font-size: 2em; + background-color: #eee; +} + +h3 { + width: 100%; + font-size: 1.5em; +} + +.function { + border-top: solid 1px #eee; +} + +.function .container { + display: flex; +} + +.function .doc { + width: 50%; +} + +.function .doc p { + text-indent: 1.5em; +} + +.function .example { + width: 50%; + flex-grow: 2; + flex-basis: auto; + overflow-x: scroll; +} + +.function .example code { + border-radius: 5px; + border: solid 1px #000; +} + +@media all and (max-width: 800px) { + .function .container { + flex-direction: column; + } + + .function .doc, .function .example { + width: 100%; + } +} diff --git a/package.json b/package.json index d94f0d8..1cfe83a 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,7 @@ "dog api" ], "author": "Brett Langdon (http://brett.is)", - "contributors":[ + "contributors": [ "colinjonesx (http://www.thetestpeople.com)", "dalehamel (http://blog.srvthe.net)" ], @@ -28,5 +28,11 @@ "gitHead": "f388635a5ab4f4da25702dc0999385d437bdf2bc", "dependencies": { "extend": "^2.0.0" + }, + "devDependencies": { + "docast": "^0.1.1", + "glob": "^5.0.3", + "js-yaml": "^3.2.7", + "marked": "^0.3.3" } }