I am close to finishing the next version, so feedback is welcome at this point!
Install the preview release:
$ npm install -g jsdoc-to-markdown@next
try it for yourself:
$ jsdoc2md your-code.js
take a look at, and experiment with some new options:
$ jsdoc2md --help
Anyway, back to the regular documentation:
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.
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
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)
Tested on Mac OSX, Linux, Windows 8.1 and Windows XP.
Document your source code using correct jsdoc syntax, then run it through jsdoc2md
.
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
$ 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
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));
});
Example
var jsdoc2md = require("jsdoc-to-markdown");
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
- [template]
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.