styledocco - npm Package Compare versions

Comparing version 0.4.1 to 0.5.0

cli.js

@@ -10,5 +10,6 @@ 'use strict';
 var mkdirp = require('mkdirp');
-var ncss = require('ncss');
+// var mincss = require('ncss');
+var mincss = function(str) { return str; };
 var path = require('path');
-var uglify = require('uglify-js');
+var minjs = require('uglify-js');
 
@@ -19,2 +20,6 @@ var styledocco = require('./styledocco');
 
+// Helper functions
+var add = function(a, b) { return a + b; };
+var readFileSync = function(file) { return fs.readFileSync(file, 'utf-8'); };
+
 // Get a filename without the extension
@@ -43,7 +48,7 @@ var baseFilename = function(str) {
 // Return content of first existing file in argument list.
-var readFirstFile = function() {
+var readFirstFileSync = function() {
   var files = [].slice.call(arguments);
   for (var i = 0, len = files.length; i < len; i++) {
     if (path.existsSync(files[i])) {
-      return fs.readFileSync(files[i], 'utf-8');
+      return readFileSync(files[i]);
     }
@@ -95,21 +100,32 @@ }
   // Compile custom or default template
-  var template = jade.compile(readFirstFile(
-    options.resources + '/docs.jade',
-    defaultResourceDir + '/docs.jade'
-  ));
+  var template = jade.compile(
+    readFirstFileSync(options.resources + '/docs.jade',
+                      defaultResourceDir + '/docs.jade')
+  );
 
-  // Get custom or default CSS file
-  var styledoccoCss =
-    readFirstFile(options.include) +
-    readFirstFile(
-      options.resources + '/docs.css',
-      defaultResourceDir + '/docs.css'
-    );
+  // Get custom or default JS and CSS files
+  var staticFiles = {
+    'docs.js': readFirstFileSync(options.resources + '/docs.js',
+                                 defaultResourceDir + '/docs.js'),
+    'docs.css': readFirstFileSync(options.resources + '/docs.css',
+                                  defaultResourceDir + '/docs.css'),
+    'previews.js': readFirstFileSync(options.resources + '/previews.js',
+                                     defaultResourceDir + '/previews.js')
+  };
 
-  // Get custom or default JS file
-  var js = readFirstFile(
-    options.resources + '/docs.js',
-    defaultResourceDir + '/docs.js'
+  // Get optional extra CSS for previews
+  var previewCSS = mincss(options.include
+    .filter(function(file) { return path.extname(file) === '.css'; })
+    .map(readFileSync)
+    .reduce(add, '')
   );
 
+  // Get optional extra JavaScript for previews
+  var previewJS = minjs(options.include
+    .filter(function(file) { return path.extname(file) === '.js'; })
+    .map(readFileSync)
+    .reduce(add, '')
+  );
+
+
   // Render template
@@ -122,4 +138,4 @@ var render = function(source, sections, css) {
       project: { name: options.name, menu: menu },
-      css: ncss(css + styledoccoCss),
-      js: uglify(js)
+      previewCSS: mincss(css) + previewCSS,
+      previewJS: previewJS
     });
@@ -168,10 +184,21 @@ };
   async.mapSeries(files, function(file, cb) {
-    var content = fs.readFileSync(file, 'utf-8');
     preprocess(file, function(err, css) {
       cb(null, {
         path: file,
-        html: render(file, styledocco(content), css)
+        css: css
       });
     });
   }, function(err, htmlFiles) {
+
+    var css = htmlFiles.reduce(function(css, file) {
+      return css + file.css;
+    }, '');
+
+    htmlFiles = htmlFiles.map(function(file) {
+      return {
+        path: file.path,
+        html: render(file.path, styledocco(readFileSync(file.path)), css)
+      };
+    });
+
     // Look for a README file.
@@ -182,16 +209,21 @@ var readmeFile = findFile(options.basePath, /^readme/i) ||
                      defaultResourceDir + '/README.md';
-    var readme = fs.readFileSync(readmeFile, 'utf-8');
-
     // Add readme with "fake" index path
     htmlFiles.push({
       path: path.join(options.basePath, 'index'),
-      html: render('', [ { docs: marked(readme), code: '' } ])
+      html: render('', styledocco.makeSections([ { docs: readFileSync(readmeFile), code: '' } ]), css)
     });
 
     // Write files to the output dir.
-    htmlFiles.map(function(file) {
+    htmlFiles.forEach(function(file) {
       var dest = path.join(options.out, htmlFilename(file.path, options.basePath));
       log('styledocco: writing ' + file.path + ' -> ' + dest);
-      return fs.writeFileSync(dest, file.html);
+      fs.writeFileSync(dest, file.html);
     });
+
+    // Write static resources to the output dir
+    Object.keys(staticFiles).forEach(function(file) {
+      var dest = path.join(options.out, file);
+      log('styledocco: writing ' + file + ' -> ' + dest);
+      fs.writeFileSync(dest, staticFiles[file]);
+    });
   });
@@ -198,0 +230,0 @@ };

package.json

@@ -6,3 +6,3 @@ {
   "author": "Jacob Rask <[e-mail]>",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "homepage": "http://jacobrask.github.com/styledocco/",
@@ -20,6 +20,7 @@ "licenses": [ { "type": "MIT", "url": "http://github.com/jacobrask/styledocco/raw/master/LICENSE" } ],
     "mkdirp": "0.x.x",
-    "ncss": "1.1.x",
     "optimist": "0.x.x",
     "uglify-js": "1.2.x" },
   "devDependencies": {
+    "browserify": "1.13.x",
+    "jquery-browserify": "1.7.x",
     "jshint": "0.7.x",
@@ -31,4 +32,5 @@ "nodeunit": "0.7.x"
   "scripts": {
-    "test": "nodeunit test"
+    "test": "nodeunit test",
+    "prepublish": "make"
   }
 }

README.md

@@ -1,12 +0,7 @@
-```
- _______ __         __        _____
-|     __|  |_.--.--|  |-----.|     \-----.----.----.-----.
-|__     |   _|  |  |  |  -__||  --  | _  |  __|  __|  _  |
-|_______|____|___  |__|_____||_____/_____|____|____|_____|
-             |_____|
-```
+StyleDocco
+==========
 
 StyleDocco generates documentation and style guide documents from your stylesheets.
 
-Stylesheet comments will be parsed through [Markdown](http://en.wikipedia.org/wiki/Markdown) and displayed in a generated HTML document. You can write code examples prefixed with 4 spaces or between [code fences](http://github.github.com/github-flavored-markdown/) (<code>```</code>) in your comments, and StyleDocco both renders the HTML and shows the code example.
+Stylesheet comments will be parsed through [Markdown](http://en.wikipedia.org/wiki/Markdown) and displayed in a generated HTML document. You can write HTML code prefixed with 4 spaces or between [code fences](http://github.github.com/github-flavored-markdown/) (<code>```</code>) in your comments, and StyleDocco renders a preview with the styles applied, and shows the example HTML code.
 
@@ -18,14 +13,12 @@ An important philosophy of StyleDocco is to introduce as little custom syntax as possible, maintaining the stylesheet comments readable and useful even without StyleDocco.
 
-## Installation
+Installation
+------------
 
-StyleDocco requires [Node.js](http://nodejs.org). After installing Node.js, run
+StyleDocco requires [Node.js](http://nodejs.org). After installing Node.js, run `npm install -g styledocco` or clone this repository.
 
-    npm install -g styledocco
-
-or check out this repository.
-
 StyleDocco is free software, released under the [MIT license](https://raw.github.com/jacobrask/styledocco/master/LICENSE).
 
 
-## Usage
+Usage
+=====
 
@@ -38,13 +31,15 @@ `styledocco [options] [INPUT]`
 
-### Options
+Options
+-------
 
  * `--name`, `-n`      Name of the project *(required)*
  * `--out`, `-o`       Output directory *(default: "docs")*
- * `--resources`, `-s` Directory with files to customize the documentation output (docs.jade, docs.css and docs.js). StyleDocco defaults will be used for any required file not found in this directory. *(optional)*
+ * `--resources`, `-s` Directory with files to customize the documentation output. StyleDocco defaults will be used for any required file not found in this directory. *(optional)*
  * `--preprocessor`    Custom preprocessor command. *(optional)* (ex: `--preprocessor "scss --load-path=deps/"`)
- * `--include`         Prepend specified CSS file to the documentation stylesheet. *(optional)* (ex: `--include mysite.css`)
+ * `--include`         Include specified CSS and/or JavaScript files in the previews. *(optional)* (ex: `--include mysite.css --include app.js`)
  * `--verbose`         Show log messages when generating the documentation. *(default: false)*
  *                     Directory containing the stylesheets to document.
 
-### Usage examples
+Usage examples
+--------------
 
@@ -60,24 +55,30 @@ Generate documentation for *My Project* in the `docs` folder, from the files in the `css` directory.
 
-## Syntax examples
+Syntax
+------
 
-    /* Provides extra visual weight and identifies the primary action in a set of buttons.
+```css
+/* Provides extra visual weight and identifies the primary action in a set of buttons.
 
-        <button class="btn primary">Primary</button> */
-    .btn.primary {
-        background: blue;
-        color: white;
-    }
+    <button class="btn primary">Primary</button> */
+.btn.primary {
+    background: blue;
+    color: white;
+}
+```
 
-Would display the description, a rendered button as well as the example HTML code. The CSS will be included in the `style` element of the document.
+Would display the description, a rendered button as well as the example HTML code. The CSS will be applied to the preview.
 
 See the `examples` folder for more in-depth examples.
 
-### Tips and tricks
+Tips and tricks
+---------------
 
  * Put some whitespace before a comment block to exclude it from the documentation.
- * Horizontal rules (`-----`, `* * *`, etc) will automatically create a new section in the documentation.
+ * Level 1 headings will automatically create a new section in the documentation.
+ * Add `:hover`, `:focus`, etc as class names in example code and the pseudo class styles will be applied in the preview.
 
 
-## Acknowledgements
+Acknowledgements
+----------------
 
 A lot of the heavy lifting in StyleDocco is done by the excellent [Marked](https://github.com/chjj/marked) module by Christopher Jeffrey. The original [Docco](https://github.com/jashkenas/docco) by Jeremy Ashkenas and [Knyle Style Sheets](https://github.com/kneath/kss) have also been sources of inspiration for StyleDocco.

styledocco.js

@@ -86,11 +86,11 @@ 'use strict';
     .map(function(block) {
-      // If we encounter code blocks in documentation, add example HTML
+      // If we encounter code blocks in documentation, add preview HTML
       var newBlock = {
         code: block.code,
         docs: block.docs.reduce(function(tokens, token) {
-          if (token.type === 'code') {
+          if (token.type === 'code' && (token.lang == null || token.lang === 'html')) {
             tokens.push({
               type: 'html',
               pre: true,
-              text: "<div class=\"styledocco-example\">" + token.text + "</div>"
+              text: '<div class="preview">' + token.text + '</div>'
             });
@@ -107,19 +107,18 @@ }
     .reduce(function(sections, cur) {
-      // Split into sections with hr's as delimiters.
-      var doc;
+      // Split into sections with headings as delimiters.
       var docs = cur.docs;
-      // TODO: Make more elegant and easy to follow.
       while (docs.length) {
-        if (sections.length === 0) {
-          // First section
-          sections.push({ docs: [ docs.shift() ], code: '' });
-        } else if (docs[0].type === 'hr') {
-            // New section, ignore the hr.
-            docs.shift();
-            if (docs.length) {
-              sections.push({ docs: [ docs.shift() ], code: '' });
-            } else {
-              // Nothing more after the hr in the doc block, start new section.
-              sections.push({ docs: [], code: '' });
-            }
+        if (docs[0].type === 'heading' && docs[0].depth === 1) {
+          // New section, add title property and strip heading.
+          var title = docs[0].text;
+          docs.shift();
+          if (docs.length === 0) {
+            // Nothing more after the heading in the doc block, start new section.
+            sections.push({ docs: [], code: '', title: title });
+          } else {
+            sections.push({ docs: [ docs.shift() ], code: '', title: title });
+          }
+        // First section
+        } else if (sections.length === 0) {
+          sections.push({ docs: [ docs.shift() ], code: '', title: null });
         } else {
@@ -132,5 +131,6 @@ // Add the documentation to the last section.
       }
-      // Add code to last section.
+      // No docs in file, just add the CSS.
       if (sections.length === 0) {
         sections.push(cur);
+      // Add remaining code to the last section.
       } else {
@@ -144,2 +144,3 @@ sections[sections.length-1].code += cur.code;
       return {
+        title: section.title ? section.title.trim() : '',
         docs: trimNewLines(marked.parser(section.docs)),
@@ -146,0 +147,0 @@ code: trimNewLines(section.code)

No alert changes

Improved metrics

Total package byte prevSize

141682

increased by114.32%

Dependency count

7

decreased by-12.5%

Lines of code

1317

increased by99.55%

Number of lines in readme file

82

increased by1.23%

Worsened metrics

Dev dependency count

4

increased by100%

Number of package files

16

decreased by-15.79%

Dependency changes

• - Removedncss@1.1.x

• - Removedncss@1.1.1(transitive)