dox-docco - npm Package Compare versions

Comparing version 0.0.2 to 0.1.0

lib/dox-docco.js

@@ -0,2 +1,5 @@
+/** */
+/* dox-docco */
 var _ = require("lodash"),
+  async = require("async"),
   dox = require("dox"),
@@ -6,9 +9,12 @@ dust = require("dust.js"),
   path = require("path"),
+  cp = require("child_process"),
+  exec = cp.exec,
+  spawn = cp.spawn,
   dox_docco,
+  dd_options,
+  commentsJson,
   emptyFn = function () {},
-  loadTemplate = _.memoize(function (filename) {
-    filename = filename || path.join(__dirname, "..", "static", "template.html");
-    var templateSrc = fs.readFileSync(filename) + "";
-    dust.loadSource(dust.compile(templateSrc, "dox_docco"));
-  });
+  pygmentize,
+  loadTemplate,
+  render;
 
@@ -18,3 +24,3 @@ dox_docco = function (options, callback) {
 
-  options = options || {};
+  dd_options = options = options || {};
   callback = callback || emptyFn;
@@ -26,13 +32,93 @@
 
-  var commentsJson = dox.parseComments(options.buffer, options);
+  options.json = dox.parseComments(options.buffer, options);
 
-  try {
-    loadTemplate(options.template);
-  } catch (e) {
-    return callback(new Error("Error loading template: " + options.template));
-  }
+  async.waterfall([
+    pygmentize,
+    loadTemplate,
+    render
+  ], callback);
 
+};
+
+pygmentize = function (callback) {
+  "use strict";
+  var options = dd_options,
+  run_pyg = function (code, callback) {
+    var out = "",
+      pyg = spawn("pygmentize", [
+        "-l", "javascript",
+        "-f", "html",
+        "-O", ""
+      ]);
+    pyg.stderr.on("data", function (err) {
+      pyg.off("exit");
+      return callback(err);
+    });
+    pyg.stdout.on("err", function () {
+      pyg.off("exit");
+      return callback(new Error("Couldn't pygmentize source."));
+    });
+    pyg.stdout.on("data", function (data) {
+      out += data;
+    });
+    pyg.on("exit", function () {
+      return callback(null, out);
+    });
+    pyg.stdin.write(code);
+    pyg.stdin.end();
+  };
+
+  /* check for pygments */
+  exec("pygmentize -V", function (err, stdout, stderr) {
+    if (err || stderr) {
+      /* silently fail if pygments isn't installed */
+      _.each(options.json, function (entry) {
+        // escape special chars (to match what pygments does)
+        entry.code = (entry.code || "")
+          .replace(/&/g, "&")
+          .replace(/</g, "&lt;")
+          .replace(/>/g, "&gt;");
+      });
+      return callback(null, options);
+    }
+    async.forEach(options.json, function (entry, callback) {
+      run_pyg(entry.code || "", function (err, stdout) {
+        if (err) {
+          return callback(new Error("Error pygmentizing: " + (err.message || err)));
+        }
+        entry.code = stdout.replace("<div class=\"highlight\"><pre>", "").replace("</pre></div>", "");
+        callback(null);
+      });
+    }, function (err) {
+      if (err) {
+        return callback(new Error("Error running pygmentize: " + err));
+      }
+      return callback(null, options);
+    });
+  });
+};
+
+loadTemplate = function (options, callback) {
+  "use strict";
+  var filename = options.template || path.join(__dirname, "..", "static", "template.html");
+  fs.readFile(filename, function (err, data) {
+    if (err) {
+      return callback(new Error("Error loading template: " + filename));
+    }
+    var templateSrc = data + "";
+    try {
+      dust.loadSource(dust.compile(templateSrc, "dox_docco"));
+    } catch (e) {
+      return callback(new Error("Error compiling template."));
+    }
+    return callback(null, options);
+  });
+};
+
+render = function (options, callback) {
+  "use strict";
   dust.render("dox_docco", {
-    filename: options.filename || "",
-    entries: commentsJson,
+    filename: options.infile || "",
+    title: options.title || (options.infile && _.last(options.infile.split(path.sep))) || "",
+    entries: options.json,
     css: options.css || "http://aearly.github.com/dox-docco/static/docco.css"
@@ -42,5 +128,5 @@ }, function (err, data) {
   });
-
 };
 
+
 module.exports = dox_docco;

package.json

 {
   "name": "dox-docco",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "A docco-like formatter for the dox comment parser",
   "main": "lib/dox-docco.js",
   "bin": "bin/dox-docco",
+  "preferGlobal": true,
   "scripts": {
@@ -28,3 +29,4 @@ "test": "mocha"
     "commander": "~1.1.1",
-    "lodash": "~1.0.0-rc.2"
+    "lodash": "~1.0.0-rc.2",
+    "async": "~0.1.22"
   },
@@ -31,0 +33,0 @@ "devDependencies": {

README.md

 dox-docco
 =========
 
-A docco-like formatter for the dox comment parser
+A [docco](http://jashkenas.github.com/docco/)-like formatter for the [dox](https://github.com/visionmedia/dox) comment parser using [Dust.js](http://akdubya.github.com/dustjs/)
 
 [![Build Status](https://travis-ci.org/aearly/dox-docco.png)](https://travis-ci.org/aearly/dox-docco)
 
+Install
+-------
+`npm install -g dox-docco`
+
+For pygments support, install `python-setuptools`, then
+
+`sudo easy_install pygments`
+
+If pygments is not installed, syntax highlighting will be skipped.
+
+
+Usage
+-----
+```
+Usage: dox-docco [options]
+
+Options:
+
+  -h, --help                 output usage information
+  -V, --version              output the version number
+  -o, --outfile [outfile]    the file to output to.  Default is stdout
+  -i, --infile [infile]      the file to read in.  Deafult is stdin
+  -c, --css [css]            The css file to use.  Default is github hosted static/docco.css.
+  -t, --template [template]  The dust template to use.  Default is static/template.html.
+  --title [title]            The title of the output document.  Deafult is the input file name, or '' for stdin
+```
+
+
 How does this differ from Docco?
 --------------------------------
 
-Dox parses block style JS comments,  while Docco parses single-line comments.  In effect, this is Docco for block-style comments.  I also wanted to create an example template using Dust.js for the output of Dox.
+Dox parses block style JS comments,  while Docco parses single-line comments.  In effect, this is Docco for block-style comments.  I also wanted to create an example Dox template using Dust.js.  This basically glues these 3 technologies together.

test/all.test.js

 var _ = require("lodash"),
   expect = require("expect.js"),
   jsdom = require("jsdom"),
+  fs = require("fs"),
   path = require("path"),
+  exec = require("child_process").exec,
   parser = require("../lib/dox-docco"),
@@ -82,1 +84,74 @@ simpleJs = "/* comment */\nfunction foo(bar) {return bar + 1; }";
 });
+
+
+describe("dox-docco CLI", function () {
+  it("should work with stdin", function (done) {
+    exec("./bin/dox-docco < ./test/fixtures/sample.js", function (err, stdout, stderr) {
+      expect(stderr).to.equal("");
+      expect(err).to.equal(null);
+      dom(stdout, function ($) {
+        expect($("td.docs").length).to.equal(2);
+        done();
+      });
+    });
+  });
+
+  it("should work with an infile", function (done) {
+    exec("./bin/dox-docco -i ./test/fixtures/sample.js", function (err, stdout, stderr) {
+      expect(stderr).to.equal("");
+      expect(err).to.equal(null);
+      dom(stdout, function ($) {
+        expect($("td.docs").length).to.equal(2);
+        done();
+      });
+    });
+  });
+
+  it("should work with an outfile", function (done) {
+    exec("./bin/dox-docco -i ./test/fixtures/sample.js " +
+      "-o out.html", function (err, stdout, stderr) {
+      expect(stderr).to.equal("");
+      expect(stdout).to.equal("");
+      expect(err).to.equal(null);
+      var buffer = fs.readFileSync("out.html") + "";
+      dom(buffer, function ($) {
+        expect($("td.docs").length).to.equal(2);
+        fs.unlink("out.html", done);
+      });
+    });
+  });
+  it("should support the `title` arg", function (done) {
+    exec("./bin/dox-docco < ./test/fixtures/sample.js " +
+      "--title \"foo\"", function (err, stdout, stderr) {
+      expect(stderr).to.equal("");
+      expect(err).to.equal(null);
+      dom(stdout, function ($) {
+        expect($("td.docs").length).to.equal(2);
+        expect($("title").html()).to.equal("foo");
+        done();
+      });
+    });
+  });
+  it("should support the `template` arg", function (done) {
+    exec("./bin/dox-docco < ./test/fixtures/sample.js " +
+      "-t ./test/fixtures/override.html", function (err, stdout, stderr) {
+      expect(stderr).to.equal("");
+      expect(err).to.equal(null);
+      dom(stdout, function ($) {
+        expect($("title").html()).to.equal("OVERRIDE");
+        done();
+      });
+    });
+  });
+  it("should support the css arg", function (done) {
+    exec("./bin/dox-docco < ./test/fixtures/sample.js " +
+      "-c override.css", function (err, stdout, stderr) {
+      expect(stderr).to.equal("");
+      expect(err).to.equal(null);
+      dom(stdout, function ($) {
+        expect($("link").attr("href")).to.equal("override.css");
+        done();
+      });
+    });
+  });
+});

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Shell access

Supply chain risk

This module accesses the system shell. Accessing the system shell increases the risk of executing arbitrary code.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

20902

increased by38.92%

Number of package files

13

increased by8.33%

Lines of code

457

increased by54.39%

Number of lines in readme file

40

increased by233.33%

Worsened metrics

Dependency count

5

increased by25%

Number of low supply chain risk alerts

2

increased by100%

Number of medium supply chain risk alerts

2

increased byInfinity%

Dependency changes

• + Addedasync@~0.1.22

• + Addedasync@0.1.22(transitive)