inno-v / jsdoc-to-markdown

Markdown API documentation generator, good for Github projects

Preview release, massive update in progress..

#jsdoc-to-markdown jsdoc documented source code in, markdown out.

This module connects the output of jsdoc-parse to the input of dmd. For information about the markdown output, customising templates etc. please read the dmd docs.

##Synopsis write documented code:

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

get markdown docs:

$ jsdoc2md example/function.js

#protection(cloak, dagger)
a quite wonderful function

**Params**

- cloak `object` - privacy gown
- dagger `object` - security

**Returns**: `survival`

this command achieves the same result:

$ jsdoc-parse example/function.js | dmd

##Examples These projects have readme files rendered by jsdoc2md:

• handbrake-js (exports an object with inner class)
• array-tools (exports a object)
• file-set (exports a class)
• command-line-args (exports a class)

##Compatible Platforms Tested on Mac OSX, Linux, Windows 8.1 and Windows XP.

##Usage Document your source code using correct jsdoc syntax, then run it through jsdoc2md.

###Command-line tool Install jsdoc2md globally:

$ npm install -g jsdoc-to-markdown

Options:

$ jsdoc2md -h

  jsdoc-to-markdown
  Markdown API documentation generator, good for Github projects

  Usage
  $ jsdoc2md [<options>] <source_files>

  --src <array>             A list of javascript source files or glob expressions
  -t, --template <string>   A custom handlebars template to insert the rendered documentation into
  -j, --json                Output the parsed jsdoc data only
  -v, --verbose             More verbose error reporting
  -h, --help                Print usage information
  --private                 Include symbols marked @private in the output
  -s, --stats               Print a few stats about the doclets parsed.
  --heading-depth <number>  root heading depth to begin the documentation from, defaults to 1 (`#`).
  -p, --plugin <array>      Use an installed package containing helper and/or partial overrides
  --helper <array>          handlebars helper files to override or extend the default set
  --partial <array>         handlebars partial files to override or extend the default set

Some typical use cases:

$ # dump everything you have into a single file
$ jsdoc src/**/*.js > api.md

$ # split into separate files
$ jsdoc src/main-module.js > main-module.md
$ jsdoc src/important-class.js > important-class.md

$ # embed documentation into a template you made
$ jsdoc src/**/*.js --template readme.hbs > README.md

###Bundled with your project ####As an npm run task

$ npm install jsdoc-to-markdown --save-dev

Then add a docs build script to your package.json, e.g.:

{
  "name": "my-web-app",
  "version": "1.0.0",
  "scripts": {
    "docs": "jsdoc2md lib/*.js > api.md"
  }
}

Docs are generated like so:

$ npm run docs

####As a grunt plug-in See grunt-jsdoc-to-markdown.

####As a gulp task Currently, the most reliable and natural way of using jsdoc2md with gulp. If your source code contains @module tags, use this method only (reason). You should only need to edit src, dest and options:

var jsdoc2md = require("jsdoc-to-markdown");
var gutil = require("gulp-util");
var fs = require("fs");

gulp.task("docs", function(done){
    var src = "lib/**/*.js";
    var dest = "api.md";
    var options = {};
    
    gutil.log("writing documentation to " + dest);
    jsdoc2md.render(src, options)
        .on("error", function(err){
            gutil.log(gutil.colors.red("jsdoc2md failed"), err.message);
        })
        .pipe(fs.createWriteStream(dest));
});

####As a gulp plug-in See gulp-jsdoc-to-markdown.

###Library Example

var jsdoc2md = require("jsdoc-to-markdown");

####jsdoc2md.render(src, options) Transforms jsdoc into markdown documentation.

Params

• src string | Array.<string> - The javascript source file(s).
• options object - The render options
  • [template] string - A custom handlebars template to insert the rendered documentation into.
  • [json] boolean - Output the parsed jsdoc data only
  • [private] boolean - Include symbols marked @private in the output
  • [stats] boolean - Print a few stats about the doclets parsed
  • [heading-depth] number - root heading depth, defaults to 1 (#)
  • [plugin] string | Array.<string> - Use an installed package containing helper and/or partial overrides
  • [helper] string | Array.<string> - handlebars helper files to override or extend the default set
  • [partial] string | Array.<string> - handlebars partial files to override or extend the default set

Returns: stream - A transform stream containing the rendered markdown
Example
Two ways to use render. Either pass in filepaths (** glob matching supported) of javascript source files:

> jsdoc2md.render("lib/*.js").pipe(process.stdout);

or pipe in source code from another source:

> fs.createReadStream("lib/main.js").pipe(jsdoc2md.render()).pipe(process.stdout);

output looks something like:

generates:
```markdown
#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.
**Params**

- sourceFiles `string` | `Array.<string>` - The javascript source file(s) - required.
- options `object` - The render options
  - [template] `string` - A handlebars template to insert your documentation into.
  - [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 1.
**Returns**: `stream` - A readable stream containing the rendered markdown

etc.
etc.