├── .eslintignore ├── .eslintrc ├── .gitignore ├── .npmignore ├── .travis.yml ├── CHANGELOG.md ├── LICENSE.md ├── README.md ├── circle.yml ├── example └── index.js ├── gulpfile.js ├── lib └── index.js ├── package.json ├── test-manual └── multi │ ├── gulpfile.js │ └── src │ ├── a.js │ ├── b.js │ └── c.js └── test ├── fixture.js └── test.js /.eslintignore: -------------------------------------------------------------------------------- 1 | html-documentation 2 | test-manual 3 | -------------------------------------------------------------------------------- /.eslintrc: -------------------------------------------------------------------------------- 1 | { 2 | "rules": { 3 | "indent": [ 4 | 2, 5 | 2 6 | ], 7 | "quotes": [ 8 | 2, 9 | "single" 10 | ], 11 | "linebreak-style": [ 12 | 2, 13 | "unix" 14 | ], 15 | "semi": [ 16 | 2, 17 | "always" 18 | ] 19 | }, 20 | "env": { 21 | "node": true 22 | }, 23 | "extends": "eslint:recommended" 24 | } 25 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | test 2 | test-manual 3 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | node_js: 3 | - '0.10' 4 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Change Log 2 | 3 | All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. 4 | 5 | 6 | ## [3.2.1](https://github.com/documentationjs/gulp-documentation/compare/v3.2.0...v3.2.1) (2017-08-11) 7 | 8 | 9 | ### Bug Fixes 10 | 11 | * **package:** update documentation to version 4.0.0-rc.0 ([2e97196](https://github.com/documentationjs/gulp-documentation/commit/2e97196)) 12 | 13 | 14 | 15 | 16 | # [3.2.0](https://github.com/documentationjs/gulp-documentation/compare/v3.0.0...v3.2.0) (2017-04-10) 17 | 18 | 19 | ### Bug Fixes 20 | 21 | * **docs:** fix broken examples in code refs [#20](https://github.com/documentationjs/gulp-documentation/issues/20) ([2cafc52](https://github.com/documentationjs/gulp-documentation/commit/2cafc52)) 22 | * **docs:** Fix straggling old-fashioned example ([d213581](https://github.com/documentationjs/gulp-documentation/commit/d213581)) 23 | 24 | 25 | ### Features 26 | 27 | * **documentation:** Update to documentation beta16, use conventional changelog ([49ab102](https://github.com/documentationjs/gulp-documentation/commit/49ab102)) 28 | 29 | 30 | 31 | 32 | # [3.1.0](https://github.com/documentationjs/gulp-documentation/compare/v3.0.0...v3.1.0) (2016-12-07) 33 | 34 | 35 | ### Bug Fixes 36 | 37 | * **docs:** fix broken examples in code refs #20 ([2cafc52](https://github.com/documentationjs/gulp-documentation/commit/2cafc52)), closes [#20](https://github.com/documentationjs/gulp-documentation/issues/20) 38 | * **docs:** Fix straggling old-fashioned example ([d213581](https://github.com/documentationjs/gulp-documentation/commit/d213581)) 39 | 40 | ### Features 41 | 42 | * **documentation:** Update to documentation beta16, use conventional changelog ([49ab102](https://github.com/documentationjs/gulp-documentation/commit/49ab102)) 43 | 44 | 45 | 46 | 47 | ## 3.0.0 48 | 49 | - Updates documentation to v4.0.0-beta12 50 | - Removes ability to pass a `documentation` instance. This would not survive 51 | major version shifts. 52 | - Switches test framework from prova to tap 53 | - Removes generated documentation results from repo 54 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | BSD 2-Clause License 2 | 3 | Copyright (c) 2016, 4 | All rights reserved. 5 | 6 | Redistribution and use in source and binary forms, with or without 7 | modification, are permitted provided that the following conditions are met: 8 | 9 | * Redistributions of source code must retain the above copyright notice, this 10 | list of conditions and the following disclaimer. 11 | 12 | * Redistributions in binary form must reproduce the above copyright notice, 13 | this list of conditions and the following disclaimer in the documentation 14 | and/or other materials provided with the distribution. 15 | 16 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 20 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 25 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # gulp-documentation 2 | 3 | [![Circle CI](https://circleci.com/gh/documentationjs/gulp-documentation.svg?style=shield)](https://circleci.com/gh/documentationjs/gulp-documentation) 4 | [![Greenkeeper badge](https://badges.greenkeeper.io/documentationjs/gulp-documentation.svg)](https://greenkeeper.io/) 5 | 6 | Use [gulp](http://gulpjs.com/) with 7 | [documentation](https://github.com/documentationjs/documentation) 8 | to generate great documentation for your JavaScript projects. 9 | 10 | ## Installation 11 | 12 | ```sh 13 | $ npm install --save-dev gulp-documentation 14 | ``` 15 | 16 | ## API 17 | 18 | 19 | 20 | ### documentation 21 | 22 | Documentation stream intended for use within the gulp system. 23 | 24 | **Parameters** 25 | 26 | - `format` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** format - one of 'html', 'md', or 'json' (optional, default `md`) 27 | - `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** documentation options - the same as given to [documentation](https://github.com/documentationjs/documentation) 28 | - `options.filename` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** custom filename for md or json output 29 | - `formatterOptions` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** output options - same as given to documentation 30 | - `formatterOptions.name` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** if format is HTML, specifies the name of the project 31 | 32 | **Examples** 33 | 34 | ```javascript 35 | var gulpDocumentation = require('gulp-documentation'); 36 | var gulp = require('gulp'); 37 | // Out of the box, you can generate JSON, HTML, and Markdown documentation 38 | gulp.task('documentation-readme-example', function () { 39 | // Generating README documentation 40 | return gulp.src('./index.js') 41 | .pipe(gulpDocumentation('md')) 42 | .pipe(gulp.dest('md-documentation')); 43 | }); 44 | 45 | // Generating a pretty HTML documentation site 46 | gulp.task('documentation-html-example', function () { 47 | return gulp.src('./index.js') 48 | .pipe(gulpDocumentation('html')) 49 | .pipe(gulp.dest('html-documentation')); 50 | }); 51 | 52 | // Generating raw JSON documentation output 53 | gulp.task('documentation-json-example', function () { 54 | return gulp.src('./index.js') 55 | .pipe(gulpDocumentation('json')) 56 | .pipe(gulp.dest('json-documentation')); 57 | }); 58 | 59 | // Generate documentation for multiple files using normal glob syntax. 60 | // Note that this generates one documentation output, so that it can 61 | // easily cross-reference and use types. 62 | gulp.task('documentation-multiple-files', function () { 63 | return gulp.src('./src/*.js') 64 | .pipe(gulpDocumentation('md')) 65 | .pipe(gulp.dest('md-documentation')); 66 | }); 67 | 68 | 69 | // If you're using HTML documentation, you can specify additional 'name' 70 | // and 'version' options 71 | gulp.task('documentation-html-options', function () { 72 | return gulp.src('./src/*.js') 73 | .pipe(gulpDocumentation('html', {}, { 74 | name: 'My Project', 75 | version: '1.0.0' 76 | })) 77 | .pipe(gulp.dest('html-documentation')); 78 | }); 79 | 80 | // Document non-JavaScript files with JSDoc comments using polyglot: true 81 | gulp.task('documentation-for-cplusplus', function () { 82 | return gulp.src('./src/*.cpp') 83 | .pipe(gulpDocumentation('html', { polyglot: true }, { 84 | name: 'My Project', 85 | version: '1.0.0' 86 | })) 87 | .pipe(gulp.dest('html-documentation')); 88 | }); 89 | ``` 90 | 91 | Returns **[stream.Transform](https://nodejs.org/api/stream.html#stream_class_stream_transform)** 92 | -------------------------------------------------------------------------------- /circle.yml: -------------------------------------------------------------------------------- 1 | machine: 2 | node: 3 | version: 8 4 | -------------------------------------------------------------------------------- /example/index.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Add one to a number 3 | * 4 | * @param {Number} x input 5 | * @returns {Number} that number plus one 6 | */ 7 | function addOne(x) { 8 | return x + 1; 9 | } 10 | 11 | module.exports = addOne; 12 | -------------------------------------------------------------------------------- /gulpfile.js: -------------------------------------------------------------------------------- 1 | var documentation = require('./'), 2 | gulp = require('gulp'); 3 | 4 | gulp.task('documentation', function () { 5 | 6 | gulp.src('./index.js') 7 | .pipe(documentation({ format: 'md' })) 8 | .pipe(gulp.dest('md-documentation')); 9 | 10 | gulp.src('./index.js') 11 | .pipe(documentation({ format: 'html' })) 12 | .pipe(gulp.dest('html-documentation')); 13 | 14 | gulp.src('./index.js') 15 | .pipe(documentation({ format: 'json' })) 16 | .pipe(gulp.dest('json-documentation')); 17 | 18 | }); 19 | -------------------------------------------------------------------------------- /lib/index.js: -------------------------------------------------------------------------------- 1 | var documentation = require('documentation'); 2 | var through2 = require('through2'); 3 | var File = require('vinyl'); 4 | 5 | /** 6 | * Documentation stream intended for use within the gulp system. 7 | * 8 | * @name documentation 9 | * @param {string} [format=md] format - one of 'html', 'md', or 'json' 10 | * @param {Object} options documentation options - the same as given to [documentation](https://github.com/documentationjs/documentation) 11 | * @param {string} options.filename custom filename for md or json output 12 | * @param {Object} formatterOptions output options - same as given to documentation 13 | * @param {Object} formatterOptions.name if format is HTML, specifies the name of the project 14 | * @returns {stream.Transform} 15 | * @example 16 | * var gulpDocumentation = require('gulp-documentation'), 17 | * var gulp = require('gulp'); 18 | * // Out of the box, you can generate JSON, HTML, and Markdown documentation 19 | * gulp.task('documentation-readme-example', function () { 20 | * // Generating README documentation 21 | * return gulp.src('./index.js') 22 | * .pipe(gulpDocumentation('md')) 23 | * .pipe(gulp.dest('md-documentation')); 24 | * }); 25 | * 26 | * // Generating a pretty HTML documentation site 27 | * gulp.task('documentation-html-example', function () { 28 | * return gulp.src('./index.js') 29 | * .pipe(gulpDocumentation('html')) 30 | * .pipe(gulp.dest('html-documentation')); 31 | * }); 32 | * 33 | * // Generating raw JSON documentation output 34 | * gulp.task('documentation-json-example', function () { 35 | * return gulp.src('./index.js') 36 | * .pipe(gulpDocumentation('json')) 37 | * .pipe(gulp.dest('json-documentation')); 38 | * }); 39 | * 40 | * // Generate documentation for multiple files using normal glob syntax. 41 | * // Note that this generates one documentation output, so that it can 42 | * // easily cross-reference and use types. 43 | * gulp.task('documentation-multiple-files', function () { 44 | * return gulp.src('./src/*.js') 45 | * .pipe(gulpDocumentation('md')) 46 | * .pipe(gulp.dest('md-documentation')); 47 | * }); 48 | * 49 | * 50 | * // If you're using HTML documentation, you can specify additional 'name' 51 | * // and 'version' options 52 | * gulp.task('documentation-html-options', function () { 53 | * return gulp.src('./src/*.js') 54 | * .pipe(gulpDocumentation('html', {}, { 55 | * name: 'My Project', 56 | * version: '1.0.0' 57 | * })) 58 | * .pipe(gulp.dest('html-documentation')); 59 | * }); 60 | * 61 | * // Document non-JavaScript files with JSDoc comments using polyglot: true 62 | * gulp.task('documentation-for-cplusplus', function () { 63 | * return gulp.src('./src/*.cpp') 64 | * .pipe(gulpDocumentation('html', { polyglot: true }, { 65 | * name: 'My Project', 66 | * version: '1.0.0' 67 | * })) 68 | * .pipe(gulp.dest('html-documentation')); 69 | * }); 70 | */ 71 | module.exports = function(format, options, formatterOptions) { 72 | options = options || {}; 73 | formatterOptions = formatterOptions || {}; 74 | var files = []; 75 | format = format || 'md'; 76 | var formatter = documentation.formats[format]; 77 | if (!formatter) { 78 | throw new Error( 79 | 'invalid format given: valid options are ' + 80 | Object.keys(documentation.formats).join(', ') 81 | ); 82 | } 83 | return through2.obj( 84 | function document(file, enc, cb) { 85 | files.push(file); 86 | cb(); 87 | }, 88 | function(cb) { 89 | documentation 90 | .build( 91 | files.map(function(file) { 92 | return file.path; 93 | }), 94 | options 95 | ) 96 | .then(comments => { 97 | return formatter(comments, formatterOptions); 98 | }) 99 | .then(output => { 100 | if (format === 'json' || format === 'md') { 101 | this.push( 102 | new File({ 103 | path: options.filename || 'API.' + format, 104 | contents: new Buffer(output) 105 | }) 106 | ); 107 | } else if (format === 'html') { 108 | output.forEach(file => this.push(file)); 109 | } 110 | cb(); 111 | }); 112 | } 113 | ); 114 | }; 115 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "gulp-documentation", 3 | "description": "documentation plugin for gulp", 4 | "version": "3.2.1", 5 | "author": "Tom MacWright", 6 | "dependencies": { 7 | "through2": "^2.0.3", 8 | "vinyl": "^2.1.0" 9 | }, 10 | "peerDependencies": { 11 | "documentation": ">=4.0.0", 12 | "gulp": ">=3.0.0" 13 | }, 14 | "devDependencies": { 15 | "documentation": "^6.0.0", 16 | "gulp": "^3.9.1", 17 | "concat-stream": "^1.6.0", 18 | "cz-conventional-changelog": "^2.0.0", 19 | "husky": "^0.14.3", 20 | "lint-staged": "^7.0.4", 21 | "prettier": "^1.7.4", 22 | "standard-version": "^4.3.0", 23 | "tap": "10.7.1" 24 | }, 25 | "keywords": [ 26 | "documentation", 27 | "gulp", 28 | "gulpplugin", 29 | "jsdoc" 30 | ], 31 | "license": "BSD-2-Clause", 32 | "main": "lib/index.js", 33 | "repository": { 34 | "type": "git", 35 | "url": "git@github.com:documentationjs/gulp-documentation.git" 36 | }, 37 | "scripts": { 38 | "release": "standard-version", 39 | "precommit": "lint-staged --verbose", 40 | "format": "prettier --write '{lib,test}/**/*.js' --single-quote", 41 | "docs": "documentation readme index.js --section=API", 42 | "test": "tap test/test.js" 43 | }, 44 | "config": { 45 | "commitizen": { 46 | "path": "./node_modules/cz-conventional-changelog" 47 | } 48 | }, 49 | "lint-staged": { 50 | "*.js": [ 51 | "prettier --write --single-quote" 52 | ] 53 | } 54 | } 55 | -------------------------------------------------------------------------------- /test-manual/multi/gulpfile.js: -------------------------------------------------------------------------------- 1 | var gulpDocumentation = require('../../'), 2 | gulp = require('gulp'); 3 | 4 | gulp.task('documentation', function () { 5 | 6 | gulp.src('./src/*.js') 7 | .pipe(gulpDocumentation('md')) 8 | .pipe(gulp.dest('md-documentation')); 9 | 10 | }); 11 | 12 | gulp.task('documentation-polyglot', function () { 13 | 14 | gulp.src('./src-cpp/*.js') 15 | .pipe(gulpDocumentation('md', { polyglot: true })) 16 | .pipe(gulp.dest('cpp-documentation')); 17 | 18 | }); 19 | 20 | gulp.task('documentation-shallow', function () { 21 | 22 | gulp.src('./src/*.js') 23 | .pipe(gulpDocumentation('md', { shallow: true })) 24 | .pipe(gulp.dest('md-documentation')); 25 | 26 | }); 27 | 28 | gulp.task('documentation-name', function () { 29 | 30 | gulp.src('./src/*.js') 31 | .pipe(gulpDocumentation('html', { shallow: true }, { name: 'My Project' })) 32 | .pipe(gulp.dest('html-documentation')); 33 | 34 | }); 35 | -------------------------------------------------------------------------------- /test-manual/multi/src/a.js: -------------------------------------------------------------------------------- 1 | /** this is a */ 2 | function aFunction() {} 3 | -------------------------------------------------------------------------------- /test-manual/multi/src/b.js: -------------------------------------------------------------------------------- 1 | /** this is b */ 2 | function bFunction() {} 3 | -------------------------------------------------------------------------------- /test-manual/multi/src/c.js: -------------------------------------------------------------------------------- 1 | /** this is c */ 2 | function cFunction() {} 3 | -------------------------------------------------------------------------------- /test/fixture.js: -------------------------------------------------------------------------------- 1 | /** 2 | * This plugin does foo 3 | * @name foo 4 | */ 5 | function foo() { 6 | return 1; 7 | } 8 | 9 | foo(); 10 | -------------------------------------------------------------------------------- /test/test.js: -------------------------------------------------------------------------------- 1 | var test = require('tap').test, 2 | path = require('path'), 3 | concat = require('concat-stream'), 4 | gulp = require('gulp'), 5 | documentation = require('../'); 6 | 7 | test('gulp-documentation', function(t) { 8 | t.ok(documentation()); 9 | t.end(); 10 | }); 11 | 12 | test('gulp-documentation md', function(t) { 13 | gulp 14 | .src(path.join(__dirname, '/fixture.js')) 15 | .pipe(documentation('md', {}, {})) 16 | .on('data', function(d) { 17 | t.equal(d.path, 'API.md'); 18 | t.end(); 19 | }); 20 | }); 21 | 22 | test('gulp-documentation md custom name', function(t) { 23 | gulp 24 | .src(path.join(__dirname, '/fixture.js')) 25 | .pipe(documentation('md', { filename: 'foo.md' })) 26 | .on('data', function(d) { 27 | t.equal(d.path, 'foo.md'); 28 | t.end(); 29 | }); 30 | }); 31 | 32 | test('gulp-documentation json', function(t) { 33 | gulp 34 | .src(path.join(__dirname, '/fixture.js')) 35 | .pipe(documentation('json')) 36 | .on('data', function(d) { 37 | t.ok(JSON.parse(d.contents), 'is json'); 38 | t.end(); 39 | }); 40 | }); 41 | 42 | test('gulp-documentation html', function(t) { 43 | gulp 44 | .src(path.join(__dirname, '/fixture.js')) 45 | .pipe(documentation('html')) 46 | .pipe( 47 | concat(function(d) { 48 | t.ok(d.length === 34 || d.length === 36); 49 | t.end(); 50 | }) 51 | ); 52 | }); 53 | 54 | test('gulp-documentation exit callback', function(t) { 55 | t.plan(1); 56 | gulp 57 | .src(path.join(__dirname, '/fixture.js')) 58 | .pipe(documentation('md')) 59 | .on('end', function() { 60 | t.pass(); 61 | }) 62 | .resume(); 63 | }); 64 | --------------------------------------------------------------------------------