├── .gitignore ├── .travis.yml ├── LICENSE.md ├── README.md ├── gulpfile.js ├── lib └── gulp-jsdoc-to-markdown.js ├── package.json └── test ├── fixture ├── another.js └── code.js └── test.js /.gitignore: -------------------------------------------------------------------------------- 1 | tmp 2 | out 3 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | node_js: 3 | - '0.12' 4 | - '0.10' 5 | - 'iojs' 6 | - '4' 7 | - '5' 8 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2014-16 Lloyd Brookes <75pound@gmail.com> 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![view on npm](http://img.shields.io/npm/v/gulp-jsdoc-to-markdown.svg)](https://www.npmjs.org/package/gulp-jsdoc-to-markdown) 2 | [![npm module downloads](http://img.shields.io/npm/dt/gulp-jsdoc-to-markdown.svg)](https://www.npmjs.org/package/gulp-jsdoc-to-markdown) 3 | [![Build Status](https://travis-ci.org/jsdoc2md/gulp-jsdoc-to-markdown.svg?branch=master)](https://travis-ci.org/jsdoc2md/gulp-jsdoc-to-markdown) 4 | [![Dependency Status](https://david-dm.org/jsdoc2md/gulp-jsdoc-to-markdown.svg)](https://david-dm.org/jsdoc2md/gulp-jsdoc-to-markdown) 5 | [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard) 6 | 7 | ***This plugin is deprecated and will not work with jsdoc2md v2. To use jsdoc2md with gulp is so simple it requires only a task - not a plugin. [Please see this guide](https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-use-with-gulp).*** 8 | 9 | # gulp-jsdoc-to-markdown 10 | Plugin for [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown). Works in both buffer and streaming modes. 11 | 12 | ## Caveat 13 | If you intend to use this plugin and your code has modules, **you must always supply a name with the `@module` tag**. 14 | 15 | In other words `@module` will fail, `@module my-module` will win. 16 | 17 | If the module name is not provided, jsdoc will try to infer it from the filename of the module. However, gulp deals with streams - not files. And that stream could come from anywhere. We do not know the file name so we cannot infer the module name - so always supply it. [More info here](http://usejsdoc.org/tags-module.html). 18 | 19 | ## `gulpfile.js` examples 20 | 21 | ### One markdown file out per source file in 22 | ```js 23 | 'use strict' 24 | var fs = require('fs') 25 | var gulp = require('gulp') 26 | var gutil = require('gulp-util') 27 | var gulpJsdoc2md = require('gulp-jsdoc-to-markdown') 28 | var rename = require('gulp-rename') 29 | var concat = require('gulp-concat') 30 | 31 | gulp.task('docs', function () { 32 | return gulp.src('lib/*.js') 33 | .pipe(gulpJsdoc2md({ template: fs.readFileSync('./readme.hbs', 'utf8') })) 34 | .on('error', function (err) { 35 | gutil.log(gutil.colors.red('jsdoc2md failed'), err.message) 36 | }) 37 | .pipe(rename(function (path) { 38 | path.extname = '.md' 39 | })) 40 | .pipe(gulp.dest('api')) 41 | }) 42 | ``` 43 | 44 | ### Multiple source files in, a single markdown file out 45 | ```js 46 | 'use strict' 47 | var fs = require('fs') 48 | var gulp = require('gulp') 49 | var gutil = require('gulp-util') 50 | var gulpJsdoc2md = require('gulp-jsdoc-to-markdown') 51 | var concat = require('gulp-concat') 52 | 53 | gulp.task('docs', function () { 54 | return gulp.src('lib/*.js') 55 | .pipe(concat('all.md')) 56 | .pipe(gulpJsdoc2md({ template: fs.readFileSync('./readme.hbs', 'utf8') })) 57 | .on('error', function (err) { 58 | gutil.log('jsdoc2md failed:', err.message) 59 | }) 60 | .pipe(gulp.dest('api')) 61 | }) 62 | ``` 63 | 64 | ## Install 65 | Install this plugin: 66 | ``` 67 | $ npm install gulp-jsdoc-to-markdown --save-dev 68 | ``` 69 | If using one of the example gulpfiles above you will also need to run: 70 | ``` 71 | $ npm i gulp gulp-util gulp-concat gulp-rename --save-dev 72 | ``` 73 | 74 | * * * 75 | 76 | © 2014-16 Lloyd Brookes \<75pound@gmail.com\>. 77 | -------------------------------------------------------------------------------- /gulpfile.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | var gulp = require('gulp') 3 | var gutil = require('gulp-util') 4 | var gulpJsdoc2md = require('./') 5 | var rename = require('gulp-rename') 6 | var del = require('del') 7 | var concat = require('gulp-concat') 8 | var fs = require('fs') 9 | 10 | gulp.task('clean', function (done) { 11 | del('tmp', function () { 12 | fs.mkdirSync('tmp') 13 | fs.mkdirSync('tmp/task1') 14 | done() 15 | }) 16 | }) 17 | 18 | /* one input, one output file */ 19 | gulp.task('one', [ 'clean' ], function () { 20 | return gulp.src('test/fixture/code.js') 21 | .pipe(gulpJsdoc2md({ 'private': true, 'sort-by': 'name' })) 22 | .on('error', function (err) { 23 | gutil.log('jsdoc2md failed:', err.message) 24 | }) 25 | .pipe(rename('code.md')) 26 | .pipe(gulp.dest('tmp/one')) 27 | }) 28 | 29 | /* multiple in, multiple out */ 30 | gulp.task('two', [ 'clean' ], function () { 31 | return gulp.src('test/fixture/*.js') 32 | .pipe(gulpJsdoc2md()) 33 | .on('error', function (err) { 34 | gutil.log('jsdoc2md failed:', err.message) 35 | }) 36 | .pipe(rename(function (path) { 37 | path.extname = '.md' 38 | })) 39 | .pipe(gulp.dest('tmp/two')) 40 | }) 41 | 42 | /* multiple in, multiple out, streaming mode */ 43 | gulp.task('three', [ 'clean' ], function () { 44 | return gulp.src('test/fixture/*.js', { buffer: false }) 45 | .pipe(gulpJsdoc2md()) 46 | .on('error', function (err) { 47 | gutil.log('jsdoc2md failed:', err.message) 48 | }) 49 | .pipe(rename(function (path) { 50 | path.extname = '.md' 51 | })) 52 | .pipe(gulp.dest('tmp/three')) 53 | }) 54 | 55 | /* multiple in, one file out 56 | note: concat doesn't support streaming mode */ 57 | 58 | gulp.task('four', [ 'clean' ], function () { 59 | return gulp.src('test/fixture/*.js') 60 | .pipe(concat('all.md')) 61 | .pipe(gulpJsdoc2md({ 'private': true })) 62 | .on('error', function (err) { 63 | gutil.log('jsdoc2md failed:', err.message) 64 | }) 65 | .pipe(gulp.dest('tmp/four')) 66 | }) 67 | 68 | gulp.task('default', [ 'clean', 'one', 'two', 'three', 'four' ]) 69 | -------------------------------------------------------------------------------- /lib/gulp-jsdoc-to-markdown.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | var jsdoc2md = require('jsdoc-to-markdown') 3 | var through = require('through2') 4 | var gutil = require('gulp-util') 5 | var PluginError = gutil.PluginError 6 | var PLUGIN_NAME = 'gulp-jsdoc-to-markdown' 7 | 8 | module.exports = gulpJsdoc2md 9 | 10 | function gulpJsdoc2md (options) { 11 | return through.obj(function (file, enc, callback) { 12 | var self = this 13 | 14 | if (file.isNull()) { 15 | // Do nothing if no contents 16 | } 17 | if (file.isBuffer()) { 18 | var buf = new Buffer(0) 19 | var jsdoc2mdStream = jsdoc2md(options) 20 | jsdoc2mdStream.on('readable', function () { 21 | var chunk = this.read() 22 | if (chunk) buf = Buffer.concat([ buf, chunk ]) 23 | }) 24 | jsdoc2mdStream.on('end', function () { 25 | file.contents = buf 26 | self.push(file) 27 | return callback() 28 | }) 29 | jsdoc2mdStream.on('error', function (err) { 30 | self.emit('error', new PluginError(PLUGIN_NAME, err.message)) 31 | }) 32 | jsdoc2mdStream.end(file.contents) 33 | } 34 | 35 | if (file.isStream()) { 36 | file.contents = file.contents.pipe(jsdoc2md(options)) 37 | self.push(file) 38 | return callback() 39 | } 40 | }) 41 | } 42 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "gulp-jsdoc-to-markdown", 3 | "author": "Lloyd Brookes <75pound@gmail.com>", 4 | "version": "1.2.2", 5 | "description": "Plugin for jsdoc-to-markdown. Works in both buffer and streaming modes.", 6 | "repository": "https://github.com/jsdoc2md/gulp-jsdoc-to-markdown.git", 7 | "main": "./lib/gulp-jsdoc-to-markdown.js", 8 | "license": "MIT", 9 | "keywords": [ 10 | "gulpplugin", 11 | "jsdoc", 12 | "markdown", 13 | "generator", 14 | "documentation", 15 | "md" 16 | ], 17 | "engines": { 18 | "node": ">=0.10.0" 19 | }, 20 | "scripts": { 21 | "test": "tape test/*.js", 22 | "gulp": "gulp; echo" 23 | }, 24 | "devDependencies": { 25 | "del": "^2.2.0", 26 | "event-stream": "^3.3.2", 27 | "gulp": "^3.9.1", 28 | "gulp-concat": "^2.6.0", 29 | "gulp-rename": "^1.2.2", 30 | "tape": "^4.5.1", 31 | "vinyl": "^1.1.1" 32 | }, 33 | "dependencies": { 34 | "gulp-util": "^3.0.7", 35 | "jsdoc-to-markdown": "^1.3.4", 36 | "through2": "^2.0.1" 37 | }, 38 | "standard": { 39 | "ignore": [ 40 | "test/fixture" 41 | ] 42 | } 43 | } 44 | -------------------------------------------------------------------------------- /test/fixture/another.js: -------------------------------------------------------------------------------- 1 | /** 2 | quarter a number 3 | @param {number} - the input 4 | @return {number} 5 | */ 6 | function quarter (number) {} 7 | -------------------------------------------------------------------------------- /test/fixture/code.js: -------------------------------------------------------------------------------- 1 | /** 2 | a global 3 | @type boolean 4 | @default 5 | */ 6 | var something = true 7 | 8 | /** 9 | an invisible 10 | @type boolean 11 | @ignore 12 | */ 13 | var invisible = true 14 | 15 | /** 16 | a private 17 | @type boolean 18 | @private 19 | */ 20 | var priv = true 21 | -------------------------------------------------------------------------------- /test/test.js: -------------------------------------------------------------------------------- 1 | var es = require('event-stream') 2 | var File = require('vinyl') 3 | var test = require('tape') 4 | var gjsdoc2md = require('../') 5 | var fs = require('fs') 6 | 7 | test('streaming mode', function (t) { 8 | t.plan(2) 9 | var fakeFile = new File({ 10 | contents: fs.createReadStream('test/fixture/code.js') 11 | }) 12 | 13 | var stream = gjsdoc2md() 14 | stream.write(fakeFile) 15 | 16 | stream.once('data', function (file) { 17 | t.ok(file.isStream(), 'is a stream') 18 | 19 | file.contents.pipe(es.wait(function (err, data) { 20 | if (err) throw err 21 | t.ok(/# something/.test(data), 'correct data') 22 | })) 23 | }) 24 | }) 25 | 26 | test('buffer mode', function (t) { 27 | t.plan(2) 28 | var fakeFile = new File({ 29 | contents: new Buffer('/**\na global\n@type boolean\n@default\n*/\nvar something = true;\n') 30 | }) 31 | 32 | var stream = gjsdoc2md() 33 | stream.write(fakeFile) 34 | 35 | stream.once('data', function (file) { 36 | t.ok(file.isBuffer()) 37 | t.ok(/# something/.test(file.contents.toString())) 38 | }) 39 | }) 40 | --------------------------------------------------------------------------------