Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

added support for building documentation

  • Loading branch information...
commit 2491aa82dd4cf43f93d3ff7dd3b851d5d2e53942 1 parent 3c407a8
@dethe authored
View
78 bin/extract2.js
@@ -1,78 +0,0 @@
-var rs = require('robotskirt'),
- cheerio = require('cheerio'),
- fs = require('fs'),
- path = require('path');
-
-function markdownToHtml(markdown, callback){
- //console.log('markdownToHtml');
- var flags = ~0;
- var html = rs.toHtmlSync(markdown, flags);
- callback(html.toString());
-}
-
-var langmap = {
- javascript: 'js',
- markdown: 'md',
- python: 'py',
- ruby: 'rb'
-};
-
-function extractPrefix(line){
- return line.match(/prefix:\s*(\S+)/)[1];
-}
-
-function extractFilename(line){
- return line.match(/filename:\s*(\S+)/)[1];
-}
-
-function htmlToCodeBlocks(html, callback){
- //console.log('htmlToCodeBlocks');
- var $ = cheerio.load(html);
- var code = $('code');
- for (var i = 0; i < code.length; i++){
- var codeblock = code.eq(i);
- var language = codeblock.attr('class');
- if (!language) continue;
- var ext = langmap[language] || language;
- var text = codeblock.text().split('\n');
- var opts = {};
- var first = text[0];
- if (first.indexOf('prefix:') > -1){
- opts.prefix = extractPrefix(first);
- text.shift();
- }else if (first.indexOf('filename:') > -1){
- opts.filename = extractFilename(first);
- text.shift();
- }
- callback(text.join('\n'), ext, opts);
- }
-}
-
-function extractBlocksFromFile(src, callback){
- //console.log('extractBlocksFromFile');
- fs.readFile(src, 'utf8', function(err, markdown){
- markdownToHtml(markdown, function(html){
- //console.log('markdownToHtml callback');
- htmlToCodeBlocks(html, function(code, ext, opts){
- //console.log('htmlToCodeBlocks callback');
- if (opts && opts.filename){
- dest = opts.filename;
- }else if (opts && opts.prefix){
- dest = opts.prefix + '/' + path.basename(src, '.md') + '.' + ext;
- }else{
- dest = path.basename(src, '.md') + '.' + ext;
- }
- callback(code, dest);
- });
- });
- });
-}
-
-function test(){
- extractBlocksFromFile('bloqs/bar.md', function(code, dest){
- console.log('Block to write to %s', dest);
- console.log(code);
- });
-}
-
-test();
View
36 bloqs/button.md
@@ -6,39 +6,39 @@ This is an example of an oBloq example file. It is an intentionally simple examp
Here is where we can provide CSS which is specific to the widget. Style can also be in stylus format (encouraged) and reference global styles. Stylus can provide namespacing, I believe.
- file: button.css
-
- button{
- border-radius: 20px;
- color: green;
- }
+``` css
+button{
+ border-radius: 20px;
+ color: green;
+}
+```
## Structure
This is the template of a widget. Some notion of data content is implied. More thought needed on data models. Perhaps the data should also be namespaced?
- file: button.mustache
-
- <button class="{{class}}>{{title}}</button>
+``` moustache
+<button class="{{class}}">{{title}}</button>
+```
## Events
What events does the widget fire? What events does the widget respond to? Namespaces can be used here as well.
- file: button.js
-
- $('click', function(){
- alert('Aaargh, you got me');
- });
+```
+$('click', function(){
+ alert('Aaargh, you got me');
+});
+```
## Wireframe
We can include text descriptions of wireframes, which will automatically be rendered using the sketchy plugin for documentation purposes. For pre-generated wireframes you can just include the png here instead, but text-based are preferred (images are nice for comparing with Photoshop comps as needed).
- file: button.sketch
-
- size 150 30
- rect 0 0 150 30 Button
+``` sketch
+size 150 30
+rect 0 0 150 30 Button
+```
## Data models
View
44 bloqs/card.md
@@ -0,0 +1,44 @@
+# oBloq Card
+
+A generic "card" or rectangle of content on the page.
+
+## Template
+
+This is the framework of the card in html.
+
+``` moustache
+<div class="card">
+ {{#header}}
+ <div class="header">{{header}}</div>
+ {{/header}}
+ <div class="content">{{content}}</div>
+ {{#footer}}
+ <div class="footer">{{footer}}</div>
+ {{/footer}}
+</div>
+```
+
+## Stylesheet
+
+Default styling for a card
+
+``` css
+.card {
+ border-radius: 10px;
+ background-color: #666;
+ color: #000;
+}
+/* Namespace styles to this block */
+.card .header {
+ background-color: #000;
+ color: #333;
+ font-family: sans-serif;
+ font-size: 1.2em;
+ font-weight: bold;
+}
+.card .footer {
+ background-color: #000;
+ color: #333;
+ font-size: 0.8em;
+}
+```
View
53 bloqs/darktheme/button.md
@@ -0,0 +1,53 @@
+# oBloq Button
+
+This is an example of an oBloq example file. It is an intentionally simple example used in order to show what oBloq is capable of.
+
+## Style
+
+Here is where we can provide CSS which is specific to the widget. Style can also be in stylus format (encouraged) and reference global styles. Stylus can provide namespacing, I believe.
+
+``` css
+button{
+ border-radius: 20px;
+ color: green;
+}
+```
+
+## Structure
+
+This is the template of a widget. Some notion of data content is implied. More thought needed on data models. Perhaps the data should also be namespaced?
+
+``` moustache
+<button class="{{class}}">{{title}}</button>
+```
+
+## Events
+
+What events does the widget fire? What events does the widget respond to? Namespaces can be used here as well.
+
+```
+$('click', function(){
+ alert('Aaargh, you got me');
+});
+```
+
+## Wireframe
+
+We can include text descriptions of wireframes, which will automatically be rendered using the sketchy plugin for documentation purposes. For pre-generated wireframes you can just include the png here instead, but text-based are preferred (images are nice for comparing with Photoshop comps as needed).
+
+``` sketch
+size 150 30
+rect 0 0 150 30 Button
+```
+
+## Data models
+
+What data is needed for this module?
+
+## Permissions
+
+Who should see this module? Who can edit it? Under what conditions?
+
+## Tests
+
+Here we can describe the tests desired. Layout tests are generally: layout, card, bar, or button. Other types can be added as needed. Not sure how to add unit, performance, or event testing yet.
View
44 bloqs/darktheme/card.md
@@ -0,0 +1,44 @@
+# oBloq Card
+
+A generic "card" or rectangle of content on the page.
+
+## Template
+
+This is the framework of the card in html.
+
+``` moustache
+<div class="card">
+ {{#header}}
+ <div class="header">{{header}}</div>
+ {{/header}}
+ <div class="content">{{content}}</div>
+ {{#footer}}
+ <div class="footer">{{footer}}</div>
+ {{/footer}}
+</div>
+```
+
+## Stylesheet
+
+Default styling for a card
+
+``` css
+.card {
+ border-radius: 10px;
+ background-color: #666;
+ color: #000;
+}
+/* Namespace styles to this block */
+.card .header {
+ background-color: #000;
+ color: #333;
+ font-family: sans-serif;
+ font-size: 1.2em;
+ font-weight: bold;
+}
+.card .footer {
+ background-color: #000;
+ color: #333;
+ font-size: 0.8em;
+}
+```
View
23 bloqs/global.md
@@ -4,18 +4,17 @@ This module contains project-wide terms and definitions for CSS and Javascript
## Colours - named colours for project
- file: globals.stylus
-
- $call-to-action #963
- $highlight goldenrod
- $selection royalblue
- $background rgba(.8, .8, .8, .5)
+``` stylus
+$call-to-action #963
+$highlight goldenrod
+$selection royalblue
+$background rgba(.8, .8, .8, .5)
+```
## Fonts - named fonts and sizes for project
- file: globals.stylus
-
- $section-head 3em Georgia bold
- $section-subhead 2em Georgia bold
- $bodytext 1em Times
-
+``` stylus
+$section-head 3em Georgia bold
+$section-subhead 2em Georgia bold
+$bodytext 1em Times
+```
View
5 bloqs/layout.md
@@ -0,0 +1,5 @@
+# Layout
+
+This is where we can define our grid, establish rules for floats and other
+positioning, etc. We can also define our top-level templates here (these
+are the ones which include `<html>` elements) which structure the application.
View
7 grunt.js
@@ -2,11 +2,14 @@ module.exports = function(grunt){
grunt.initConfig({
clean: {
// Clean will recursively delete entire directories. Be careful
- all: ['build']
+ all: ['build','docs']
},
extract: {
build: ['bloqs/*.md', 'bloqs/**/*.md']
},
+ doc: {
+ docs: ['bloqs/*.md', 'bloqs/**/*.md']
+ },
lint: {
all: ['build/*.js', 'build/**/*.js']
},
@@ -23,5 +26,5 @@ module.exports = function(grunt){
}catch(e){
grunt.loadNpmTasks('obloq/tasks');
}
- grunt.registerTask('default', 'clean extract');
+ grunt.registerTask('default', 'clean extract doc');
};
View
8 index.html → lib/index.template
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8" />
<title>oBloq Examples</title>
- <link rel="stylesheet" href="lib/obloq.css">
+ <link rel="stylesheet" href="../lib/obloq.css">
<link rel="stylesheet" href="http://yandex.st/highlightjs/6.1/styles/default.min.css">
</head>
<body>
@@ -20,8 +20,8 @@
</div>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js"></script>
<script src="http://yandex.st/highlightjs/6.1/highlight.min.js"></script>
- <script src="lib/raphael_152.js"></script>
- <script src="lib/sketchy.js"></script>
- <script src="lib/obloq.js"></script>
+ <script src="../lib/raphael_152.js"></script>
+ <script src="../lib/sketchy.js"></script>
+ <script src="../lib/obloq.js"></script>
</body>
</html>
View
7 lib/obloq.js
@@ -1,5 +1,5 @@
function loadpage(hash){
- $('#example').load('build/' + hash.slice(1) + '.html?' + Math.random(), format);
+ $('#example').load(hash.slice(1).toLowerCase() + '.html?' + Math.random(), format);
}
$('#menu a').click(function(){
@@ -8,11 +8,8 @@ $('#menu a').click(function(){
function format(){
$('#example pre code').each(function(i, elem){
- var lines = $(elem).text().trim().split('\n');
- var filename = lines[0].match(/file\: +(.*)\.(.*)/);
- var ext = filename[2];
+ var ext = $(elem).attr('class');
if (ext){
- lines = lines.slice(2);
if(ext === 'sketch'){
$(elem).addClass('no-highlight').sketch();
}else{
View
2  tasks/clean.js
@@ -16,7 +16,7 @@ module.exports = function(grunt) {
var rimraf = require('rimraf');
grunt.registerMultiTask('clean', 'Delete generated files before extracting code blocks', function(){
- var files = grunt.file.expandFiles(this.file.src);
+ var files = this.file.src;
files.forEach(function(path){
rimraf.sync(path);
});
View
63 tasks/extract.js
@@ -35,6 +35,7 @@ module.exports = function(grunt) {
};
grunt.registerMultiTask('extract', 'Extract code blocks from markdown documents', function(){
+ console.log('extracting files');
var files = grunt.file.expandFiles(this.file.src);
var destfolder = this.file.dest;
files.forEach(function(src){
@@ -44,6 +45,33 @@ module.exports = function(grunt) {
});
});
+ grunt.registerMultiTask('doc', 'Build documentation from markdown documents', function(){
+ console.log('building docs');
+ var files = grunt.file.expandFiles(this.file.src);
+ var destfolder = this.file.dest;
+ var paths = [];
+ files.forEach(function(src){
+ var markdown = fs.readFileSync(src, 'utf8');
+ markdownToHtml(markdown, function(html){
+ var prefix = getNestedPath(src);
+ var filename = path.basename(src, '.md') + '.' + 'html';
+ var dest = path.join(destfolder, prefix, filename);
+ paths.push(dest);
+ console.log('saving %s', dest);
+ appendToPath(dest, html);
+ });
+ });
+ var index = fs.readFileSync('lib/index.template', 'utf8');
+ var $ = cheerio.load(index);
+ var holder = $('#menu ul');
+ holder.empty();
+ paths.forEach(function(src){
+ var name = getNamedPath(src);
+ holder.append('<li><a href="#' + name + '">' + name + '</a></li>');
+ });
+ appendToPath(path.join(destfolder, 'index.html'), $.html());
+ });
+
// We can write a file to a directory that doesn't exist yet
// This is how we make sure that it does
function ensurePath(relpath){
@@ -101,6 +129,26 @@ module.exports = function(grunt) {
}
}
+ function capitalize(name){
+ return name[0].toUpperCase() + name.slice(1);
+ }
+
+ function getNamedPath(pathname){
+ var dirs = path.dirname(pathname).split(path.sep);
+ dirs.shift();
+ dirs.push(path.basename(pathname, '.html'));
+ for (var i = 0; i < dirs.length; i++){
+ dirs[i] = capitalize(dirs[i]);
+ }
+ return dirs.join(path.sep);
+ }
+
+ function getNestedPath(pathname){
+ var dirs = path.dirname(pathname).split(path.sep);
+ dirs.shift(); // throw away the first directory of nesting
+ return dirs.join(path.sep);
+ }
+
function extractBlocksFromFile(src, callback){
//console.log('extractBlocksFromFile');
var markdown = fs.readFileSync(src, 'utf8');
@@ -108,19 +156,12 @@ module.exports = function(grunt) {
//console.log('markdownToHtml callback');
htmlToCodeBlocks(html, function(code, ext, opts){
//console.log('htmlToCodeBlocks callback');
- if (opts && opts.filename){
- dest = opts.filename;
- }else if (opts && opts.prefix){
- dest = opts.prefix + '/' + path.basename(src, '.md') + '.' + ext;
- }else{
- dest = path.basename(src, '.md') + '.' + ext;
- }
+ var prefix = opts.prefix || getNestedPath(src);
+ var filename = path.basename(src, '.md') + '.' + ext;
+ var dest = opts.dest || path.join(prefix, filename);
+ console.log('src: %s, dest: %s', src, dest);
callback(code, dest);
});
});
}
-
-
-
-
};

0 comments on commit 2491aa8

Please sign in to comment.
Something went wrong with that request. Please try again.