jsdoc-to-markdown - npm Package Compare versions

Comparing version 0.4.1 to 0.5.0

bin/cli.js

@@ -6,3 +6,4 @@ #!/usr/bin/env node
     dope = require("console-dope"),
-    jsdoc2md = require("../");
+    jsdoc2md = require("../"),
+    domain = require("domain");
 
@@ -13,5 +14,2 @@ var cli = cliArgs([
     },
-    { name: "preset", alias: "p", type: String,
-      description: "Use a preset template"
-    },
     { name: "json", alias: "j", type: Boolean,
@@ -27,4 +25,13 @@ description: "Output the template data only"
     { name: "src", type: Array, defaultOption: true,
-      description: "The javascript source files. The default option."
+      description: "The javascript source files."
     },
+    { name: "plugin", type: Array, alias: "p",
+      description: "Packages containing helper and/or partial overrides"
+    },
+    { name: "helper", type: Array,
+      description: "helper overrides"
+    },
+    { name: "partial", type: Array,
+      description: "partial overrides"
+    },
     { name: "private", type: Boolean,
@@ -34,3 +41,3 @@ description: "Include symbols marked @private in the output"
     { name: "heading-depth", type: Number,
-      description: "root heading depth to begin the documentation from, defaults to 2 (`##`)."
+      description: "root heading depth to begin the documentation from, defaults to 1 (`#`)."
     },
@@ -51,3 +58,3 @@ { name: "stats", alias: "s", type: Boolean,
 try{
-    var argv = cli.parse();
+    var argv = cli.parse({ unexpectedType: "string" });
 } catch(err){
@@ -63,7 +70,11 @@ halt(err);
 if(argv.src){
-    var renderStream = jsdoc2md.render(argv.src, argv);
-    renderStream.on("error", halt);
-    renderStream.pipe(process.stdout);
+    var d = domain.create();
+    d.on("error", halt);
+    d.run(function(){
+        var mdStream = jsdoc2md.render(argv.src, argv).pipe(process.stdout);
+    });
+    
 } else {
-    process.stdin.pipe(jsdoc2md.createRenderStream(argv)).pipe(process.stdout);
+    dope.error("No javascript source files specified, listening on stdin..");
+    process.stdin.pipe(jsdoc2md.render(argv.src, argv)).pipe(process.stdout);
 }
@@ -75,3 +86,3 @@
     } else {
-        dope.red.error(err);
+        dope.red.error(err.stack);
     }
@@ -78,0 +89,0 @@ dope.error(usage);

lib/jsdoc-to-markdown.js

 "use strict";
-var fileSet = require("file-set"),
-    boil = require("boil-js"),
-    mfs = require("more-fs"),
-    path = require("path"),
-    mfs = require("more-fs"),
-    a = require("array-tools"),
-    parse = require("jsdoc-parse"),
-    Transform = require("stream").Transform;
+var jsdocParse = require("jsdoc-parse"),
+    dmd = require("dmd"),
+    mfs = require("more-fs");
 
@@ -14,3 +9,3 @@ /**
 @alias jsdoc2md
-@example
+@example 
 ```js
@@ -21,38 +16,14 @@ var jsdoc2md = require("jsdoc-to-markdown");
 exports.render = render;
-exports.createRenderStream = createRenderStream;
 
-var partials = fileSet(path.resolve(__dirname, "../partials/**/*.hbs"));
-partials.files.forEach(function(file){
-    boil.registerPartial(
-        path.basename(file, ".hbs"),
-        mfs.read(file)
-    );
-});
-
-var helpers = fileSet(path.resolve(__dirname, "../helpers/**/*.js"));
-helpers.files.forEach(function(file){
-    require(file)(boil);
-});
-
-var compiled = {
-    default: boil.compile(mfs.read(path.resolve(__dirname, "../presets/default.hbs")))
-};
-
-function Options(options){
-    options = options || {};
-    this.preset = options.preset || "default";
-    this["heading-depth"] = options["heading-depth"] || 1;
-    this.template = options.template;
-    this.json = options.json;
-    this.private = options.private;
-}
-
 /**
-Renders the jsdoc documentation from the specified source files as markdown.
+Transforms jsdoc into markdown documentation
 @param {string | string[]} - The javascript source file(s) - required. 
 @param {object} - The render options
 @param {string} [options.template] - A handlebars template to insert your documentation into. 
-@param {string} [options.preset] - Choose from one of the built-in templates
 @param {boolean} [options.json] - Return the JSON template data only
+@param {boolean} [options.stats] - Return stats about the doclets parsed
 @param {boolean} [options.private] - Include symbols marked @private in the output
+@param {string | string[]} [options.helper] - Helper overrides
+@param {string | string[]} [options.partial] - Partial overrides
+@param {string | string[]} [options.plugin] - Packages containing helper and/or partial overrides
 @param {number} [options.heading-depth] - Root heading depth, defaults to 2.
@@ -84,6 +55,6 @@ @return {stream} A readable stream containing the rendered markdown
   - [template] `string` - A handlebars template to insert your documentation into.
-  - [preset] `string` - Choose from one of the built-in templates
   - [json] `boolean` - Return the JSON template data only
+  - [stats] `boolean` - Return a few stats about the doclets parsed
   - [private] `boolean` - Include symbols marked @private in the output
-  - [heading-depth] `number` - Root heading depth, defaults to 2.
+  - [heading-depth] `number` - Root heading depth, defaults to 1.
 
@@ -96,83 +67,16 @@ * **Returns**: `stream` - A readable stream containing the rendered markdown
 */
-function render(sourceFiles, options){
-    options = new Options(options);
-    options.src = fileSet(sourceFiles).files;
+function render(src, options){
+    options = options || {};
+    if (options.template){
+        options.template = mfs.read(options.template);
+    }
+    var jsdocStream = jsdocParse(src, options);
     
-    if (!options.src.length){
-        throw new Error("specify at least one source file");
+    if (options.json || options.stats){
+        return jsdocStream;
+    } else {
+        var mdStream = dmd(options);
+        jsdocStream.pipe(mdStream);
+        return mdStream;
     }
-
-    var docStream = parse(options);
-    var renderStream = createRenderStream(options);
-    docStream.pipe(renderStream);
-    docStream.on("error", function(err){
-        renderStream.emit("error", err);
-    });
-    return renderStream;
 }
-
-/**
-@param {object} - The render options, as specified in `render()`
-@return {stream} a stream containing the rendered markdown
-@example
-```js
-process.stdin
-    .pipe(jsdoc2md.createRenderStream({ template: "api.hbs" }))
-    .pipe(process.stdout);
-```
-@alias module:jsdoc-to-markdown.createRenderStream
-*/
-function createRenderStream(options){
-    options = new Options(options);
-    function renderTemplate(data){
-        /* make the command-line args available to the templates */
-        data.argv = options;
-        data._headingDepth = 0;
-        data._indexDepth = 0;
-
-        if (options.template){
-            var template = mfs.read(options.template);
-            if (template){
-                return boil.render(template, data);
-            } else {
-                throw new Error(template === null ? "Template file doesn't exist" : "Template file is empty");
-            }
-        } else {
-            if (compiled[options.preset]){
-                return compiled[options.preset](data);
-            } else {
-                throw new Error("preset doesn't exist: " + options.preset);
-            }
-        }
-    }
-    
-    var renderer = new Transform();
-    renderer.json = new Buffer(0);
-    renderer._transform = function(chunk, enc, done){
-        if (chunk) this.json = Buffer.concat([ this.json, chunk ]);
-        done();
-    };
-    renderer._flush = function(){
-        try {
-            var data = JSON.parse(this.json);
-        } catch(err){
-            err.message = "input json failed to parse: " + err.message;
-            throw err;
-        }
-        if (options.json){
-            this.push(this.json);
-        } else if(options.stats) {
-            var stats = {};
-            stats.memberof = a.unique(a.pluck(data, "memberof"));
-            stats.class = a.pluck(a.where(data, { kind: "class" }), "longname");
-            stats.module = a.pluck(a.where(data, { kind: "module" }), "longname");
-            
-            this.push(JSON.stringify(stats, null, "  "));
-            
-        } else {
-            this.push(renderTemplate(data));
-        }
-        this.push(null);
-    };
-    return renderer;
-}

package.json

 {
   "name": "jsdoc-to-markdown",
   "author": "Lloyd Brookes",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Markdown API documentation generator, good for Github projects",
@@ -9,9 +9,9 @@ "repository": "https://github.com/75lb/jsdoc-to-markdown",
   "scripts": {
-    "test": "",
-    "render": "node test/render.js",
+    "test": "tape test/*.js",
+    "render": "node test/fixture/render.js",
     "docs": "node bin/cli.js -t jsdoc2md/README.hbs lib/jsdoc-to-markdown.js > README.md; ",
     "watch": "baldrick --do 'npm run docs' --when test/input/*/*.js partials/* --change --speak",
-    "lint": "jshint helpers/*.js bin/*.js lib/*.js; echo",
-    "index": "jsdoc2md test/input/**/*.js > test/output/all-with-index.md",
-    "templates": "node test/templates.js",
+    "lint": "jshint bin/*.js lib/*.js test/*.js; echo",
+    "index": "jsdoc2md test/fixture/input/**/*.js > test/fixture/output/all-with-index.md",
+    "templates": "node test/fixture/templates.js",
     "all": "npm run render && npm run docs && npm run index && npm run templates;"
@@ -29,12 +29,11 @@ },
   "dependencies": {
-    "array-tools": "^1.1.0",
-    "boil-js": "^0.1.0",
-    "command-line-args": "^0.4.0",
+    "command-line-args": "^0.5.0",
     "console-dope": "^0.3.3",
-    "file-set": "^0.2",
-    "jsdoc-parse": "^0.1.0",
-    "more-fs": "^0.4.0",
-    "object-tools": "^1.0.0",
-    "string-tools": "^0.1.4"
+    "dmd": "^0.1.3",
+    "jsdoc-parse": "^0.2.2",
+    "more-fs": "^0.4.0"
+  },
+  "devDependencies": {
+    "tape": "^2.13.3"
   }
 }

README.md

 [![view on npm](http://img.shields.io/npm/v/jsdoc-to-markdown.svg)](https://www.npmjs.org/package/jsdoc-to-markdown)
 [![npm module downloads per month](http://img.shields.io/npm/dm/jsdoc-to-markdown.svg)](https://www.npmjs.org/package/jsdoc-to-markdown)
+[![Build Status](https://travis-ci.org/75lb/jsdoc-to-markdown.svg?branch=master)](https://travis-ci.org/75lb/jsdoc-to-markdown)
 [![Dependency Status](https://david-dm.org/75lb/jsdoc-to-markdown.svg)](https://david-dm.org/75lb/jsdoc-to-markdown)
@@ -11,2 +12,11 @@ ![Analytics](https://ga-beacon.appspot.com/UA-27725889-32/jsdoc-to-markdown/README.md?pixel)
 
+This app is composed from the lower-level [jsdoc-parse](https://github.com/75lb/jsdoc-parse) and [dmd](https://github.com/75lb/dmd) modules.
+
+##examples
+These projects have readme files rendered by `jsdoc2md`:
+* [handbrake-js](https://github.com/75lb/handbrake-js) (exports an object with inner class)
+* [array-tools](https://github.com/75lb/array-tools) (exports a object)
+* [file-set](https://github.com/75lb/file-set) (exports a class)
+* [command-line-args](https://github.com/75lb/command-line-args)  (exports a class)
+
 ##Install
@@ -67,105 +77,18 @@ Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`.
 
--t, --template <string>   A custom handlebars template to insert the rendered documentation into,
-                          overriding the default
--p, --preset <string>     Use a preset template ('default', 'global' or 'modules')
+-t, --template <string>   A custom handlebars template to insert the rendered documentation into
 -j, --json                Output the template data only
+-v, --verbose             More verbose output and error reporting
 -h, --help                Print usage information
 --src <array>             The javascript source files. The default option.
+-p, --plugin <array>      Packages containing helper and/or partial overrides
+--helper <array>          helper overrides
+--partial <array>         partial overrides
 --private                 Include symbols marked @private in the output
---heading-depth <number>  root heading depth to begin the documentation from, defaults to 2 (`##`).
+--heading-depth <number>  root heading depth to begin the documentation from, defaults to 1 (`#`).
+-s, --stats               Print a few stats about the doclets parsed.
 ```
 
-##examples
-These projects have readme files rendered by `jsdoc2md`:
-* [handbrake-js](https://github.com/75lb/handbrake-js) (exports an object with inner class)
-* [array-tools](https://github.com/75lb/array-tools) (exports a object)
-* [file-set](https://github.com/75lb/file-set) (exports a class)
-* [command-line-args](https://github.com/75lb/command-line-args)  (exports a class)
-
-##Templating
-Running `jsdoc2md` without a `--template` generates documentation with the default template, which looks like this:
-
-    {{>index}}
-    {{>modules}}
-    {{>globals}}
-    {{>others}}
-    
-###{{>index}}
-Only output if there are at least two modules defined. 
-
-    #Index
-    
-    * Modules
-      * {{>module-name}}
-        * {{>member-names}}
-    * Global
-      * {{>global-name}}
-
-###{{>modules}}
-Outputs one {{>module}} partial per module.
-
-###{{>globals}}
-
-    #Global
-    {{>global-index}}
-    {{>members}}
-
-###{{>members}}
-
-  {{#each (members in=data)}}{{>member}}{{/each~}}
-  {{#each (functions in=data)}}{{>function}}{{/each~}}
-  {{#each (namespaces in=data)}}{{>namespace}}{{/each~}}
-  {{#each (constants in=data)}}{{>constant}}{{/each~}}
-  {{#each (typedefs in=data)}}{{>typedef}}{{/each~}}
-  {{#each (events in=data)}}{{>event}}{{/each~}}
-  {{#each (classes in=data)}}{{>class}}{{/each~}}
-
-###{{>module}}
-
-    {{>module-head}}
-    {{>module-body}}
-    {{>module-exported}}  (either a class with index, function or object with index)
-
-###{{>module-head}}
-
-    {{>anchor}}
-    {{>heading}}{{>module-name}}
-    
-###{{>module-body}}
-
-    {{>fields}}
-    
-###{{>fields}}
-
-    {{>description~}}
-    {{>params~}}
-    {{>deprecated~}}
-    {{>augments~}}
-    {{>memberof~}}
-    {{>type~}}
-    {{>default~}}
-    {{>returns~}}
-    {{>access~}}
-    {{>enum~}}
-    {{>readOnly~}}
-    {{>since~}}
-    {{>version~}}
-    {{>authors~}}
-    {{>license~}}
-    {{>copyright~}}
-    {{>examples~}}
-
-###{{>module-exported}}
-
-    {{>class}}, {{>function}} or {{>module-index}} and {{>members}}
-
-###{{>class}}
-
-    {{>class-head}}
-    {{>class-body~}}
-    {{>class-members-index~}}
-    {{>class-members~}}
-
 ##API Reference
 **Example**  
+
 ```js
@@ -176,19 +99,17 @@ var jsdoc2md = require("jsdoc-to-markdown");
 
-**Members**
-
-* [jsdoc2md.render(sourceFiles, options)](#module_jsdoc-to-markdown.render)
-* [jsdoc2md.createRenderStream(options)](#module_jsdoc-to-markdown.createRenderStream)
-
 <a name="module_jsdoc-to-markdown.render"></a>
-##jsdoc2md.render(sourceFiles, options)
-Renders the jsdoc documentation from the specified source files as markdown.
+##jsdoc2md.render(src, options)
+Transforms jsdoc into markdown documentation
 
 **Params**
 
-- sourceFiles `string` | `Array.<string>` - The javascript source file(s) - required.
+- src `string` | `Array.<string>` - The javascript source file(s) - required.
 - options `object` - The render options
   - [template] `string` - A handlebars template to insert your documentation into.
-  - [preset] `string` - Choose from one of the built-in templates
   - [json] `boolean` - Return the JSON template data only
+  - [stats] `boolean` - Return stats about the doclets parsed
   - [private] `boolean` - Include symbols marked @private in the output
+  - [helper] `string` | `Array.<string>` - Helper overrides
+  - [partial] `string` | `Array.<string>` - Partial overrides
+  - [plugin] `string` | `Array.<string>` - Packages containing helper and/or partial overrides
   - [heading-depth] `number` - Root heading depth, defaults to 2.
@@ -217,6 +138,6 @@
   - [template] `string` - A handlebars template to insert your documentation into.
-  - [preset] `string` - Choose from one of the built-in templates
   - [json] `boolean` - Return the JSON template data only
+  - [stats] `boolean` - Return a few stats about the doclets parsed
   - [private] `boolean` - Include symbols marked @private in the output
-  - [heading-depth] `number` - Root heading depth, defaults to 2.
+  - [heading-depth] `number` - Root heading depth, defaults to 1.
 **Returns**: `stream` - A readable stream containing the rendered markdown
@@ -228,16 +149,2 @@
 
-<a name="module_jsdoc-to-markdown.createRenderStream"></a>
-##jsdoc2md.createRenderStream(options)
-**Params**
 
-- options `object` - The render options, as specified in `render()`
-
-**Returns**: `stream` - a stream containing the rendered markdown  
-**Example**  
-```js
-process.stdin
-    .pipe(jsdoc2md.createRenderStream({ template: "api.hbs" }))
-    .pipe(process.stdout);
-```
-
-

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

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

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

No tests

Quality

Package does not have any tests. This is a strong signal of a poorly maintained or low quality package.

Found 1 instance in 1 package

Improved metrics

Dependency count

5

decreased by-44.44%

Number of low quality alerts

2

decreased by-33.33%

Worsened metrics

Total package byte prevSize

104475

decreased by-17.31%

Dev dependency count

1

increased byInfinity%

Number of package files

94

decreased by-51.55%

Lines of code

1172

decreased by-23.9%

Number of lines in readme file

146

decreased by-38.91%

Number of medium supply chain risk alerts

2

increased byInfinity%

Dependency changes

• + Addeddmd@^0.1.3

• + Addedalign-text@0.1.4(transitive)

• + Addedansi-escape-sequences@1.0.2(transitive)

• + Addedcamelcase@1.2.1(transitive)

• + Addedcenter-align@0.1.3(transitive)

• + Addedcliui@2.1.0(transitive)

• + Addedcommand-line-args@0.5.9(transitive)

• + Addeddecamelize@1.2.0(transitive)

• + Addeddmd@0.1.4(transitive)

• + Addedhandlebars@3.0.8(transitive)

• + Addedhandlebars-ansi@0.2.0(transitive)

• + Addedis-buffer@1.1.6(transitive)

• + Addedjsdoc-parse@0.2.11(transitive)

• + Addedkind-of@3.2.2(transitive)

• + Addedlazy-cache@1.0.4(transitive)

• + Addedlongest@1.0.1(transitive)

• + Addedminimist@0.0.10(transitive)

• + Addedmore-fs@0.5.0(transitive)

• + Addedoptimist@0.6.1(transitive)

• + Addedrepeat-string@1.6.1(transitive)

• + Addedright-align@0.1.3(transitive)

• + Addedsource-map@0.5.7(transitive)

• + Addeduglify-js@2.8.29(transitive)

• + Addeduglify-to-browserify@1.0.2(transitive)

• + Addedwindow-size@0.1.0(transitive)

• + Addedword-wrap@1.2.5(transitive)

• + Addedwordwrap@0.0.2(transitive)

• + Addedyargs@3.10.0(transitive)

• - Removedarray-tools@^1.1.0

• - Removedboil-js@^0.1.0

• - Removedfile-set@^0.2

• - Removedobject-tools@^1.0.0

• - Removedstring-tools@^0.1.4

• - Removedansi-escape-sequences@0.0.1(transitive)

• - Removedasync@0.2.10(transitive)

• - Removedcommand-line-args@0.4.0(transitive)

• - Removedhandlebars@2.0.0(transitive)

• - Removedhandlebars-ansi@0.0.2(transitive)

• - Removedjsdoc-parse@0.1.4(transitive)

• - Removedoptimist@0.3.7(transitive)

• - Removeduglify-js@2.3.6(transitive)

• Updatedcommand-line-args@^0.5.0

• Updatedjsdoc-parse@^0.2.2