Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 1caa020

Browse files
committed
Add docs readme-generation task
1 parent 2cb89e4 commit 1caa020

File tree

5 files changed

+101
-88
lines changed

5 files changed

+101
-88
lines changed

‎README.md

Lines changed: 41 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -6,58 +6,75 @@ Use [gulp](http://gulpjs.com/) with
66
[documentation](https://github.com/documentationjs/documentation)
77
to generate great documentation for your JavaScript projects.
88

9-
| name | description |
10-
| ---- | ----------- |
11-
| `options` | output options |
12-
| `options.format` | either 'html', 'md', 'json', or 'docset' |
13-
| `options.filename` | custom filename for md or json output |
14-
15-
Returns `stream.Transform`
16-
179
## Installation
1810

1911
```sh
2012
$ npm install --save-dev gulp-documentation
2113
```
2214

23-
## Example
15+
## API
2416

25-
```js
26-
var gulpDocumentation = require('gulp-documentation'),
27-
gulp = require('gulp');
17+
### documentation
18+
19+
Documentation stream intended for use within the gulp system.
20+
21+
**Parameters**
2822

29-
/**
30-
* Out of the box, you can generate JSON, HTML, and Markdown documentation
31-
*/
23+
- `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`)
24+
- `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)
25+
- `options.filename` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** custom filename for md or json output
26+
- `formatterOptions` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** output options - same as given to documentation
27+
- `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
28+
29+
**Examples**
30+
31+
```javascript
32+
var gulpDocumentation = require('gulp-documentation'),
33+
var gulp = require('gulp');
34+
// Out of the box, you can generate JSON, HTML, and Markdown documentation
3235
gulp.task('documentation', function () {
3336

3437
// Generating README documentation
3538
gulp.src('./index.js')
36-
.pipe(gulpDocumentation({ format:'md' }))
39+
.pipe(gulpDocumentation('md'))
3740
.pipe(gulp.dest('md-documentation'));
3841

3942
// Generating a pretty HTML documentation site
4043
gulp.src('./index.js')
41-
.pipe(gulpDocumentation({ format:'html' }))
44+
.pipe(gulpDocumentation('html))
4245
.pipe(gulp.dest('html-documentation'));
4346
4447
// Generating raw JSON documentation output
4548
gulp.src('./index.js')
46-
.pipe(gulpDocumentation({ format:'json' }))
49+
.pipe(gulpDocumentation('json'))
4750
.pipe(gulp.dest('json-documentation'));
4851
4952
});
5053
51-
/**
52-
* Generate documentation for multiple files using normal glob syntax.
53-
* Note that this generates one documentation output, so that it can
54-
* easily cross-reference and use types.
55-
*/
56-
gulp.task('documentation', function () {
54+
// Generate documentation for multiple files using normal glob syntax.
55+
// Note that this generates one documentation output, so that it can
56+
// easily cross-reference and use types.
57+
gulp.task('documentation-multiple-files', function () {
5758
5859
gulp.src('./src/*.js')
5960
.pipe(gulpDocumentation({ format: 'md' }))
6061
.pipe(gulp.dest('md-documentation'));
6162
6263
});
64+
65+
66+
// If you're using HTML documentation, you can specify additional 'name'
67+
// and 'version' options
68+
gulp.task('documentation-html-options', function () {
69+
70+
gulp.src('./src/*.js')
71+
.pipe(gulpDocumentation('html', {}, {
72+
name: 'My Project',
73+
version: '1.0.0'
74+
}))
75+
.pipe(gulp.dest('html-documentation'));
76+
77+
});
6378
```
79+
80+
Returns **[stream.Transform](https://nodejs.org/api/stream.html#stream_class_stream_transform)**

‎index.js

Lines changed: 48 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -6,66 +6,64 @@ var File = require('vinyl');
66
* Documentation stream intended for use within the gulp system.
77
*
88
* @name documentation
9-
* @param {Object} options output options
10-
* @param {string} options.format either 'html', 'md', 'json', or 'docset'
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)
1111
* @param {string} options.filename custom filename for md or json output
12-
* @param {Object} [documentation] your custom instance of documentation.js
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
1314
* @returns {stream.Transform}
1415
* @example
15-
* var documentation = require('./'),
16-
* gulp = require('gulp');
17-
*
16+
* var gulpDocumentation = require('gulp-documentation'),
17+
* var gulp = require('gulp');
18+
* // Out of the box, you can generate JSON, HTML, and Markdown documentation
1819
* gulp.task('documentation', function () {
20+
*
21+
* // Generating README documentation
1922
* gulp.src('./index.js')
20-
* .pipe(documentation({
21-
* format: 'html'
22-
* }))
23-
* .pipe(gulp.dest('documentation'));
24-
* });
25-
*
26-
* // documentation with JSON output, default filename API.md
27-
* gulp.task('documentation-json', function () {
23+
* .pipe(gulpDocumentation('md'))
24+
* .pipe(gulp.dest('md-documentation'));
25+
*
26+
* // Generating a pretty HTML documentation site
2827
* gulp.src('./index.js')
29-
* .pipe(documentation({
30-
* format: 'json'
31-
* }))
32-
* .pipe(gulp.dest('documentation'));
33-
* });
34-
*
35-
* // documentation with markdown output, default filename API.md
36-
* gulp.task('documentation-md', function () {
28+
* .pipe(gulpDocumentation('html))
29+
* .pipe(gulp.dest('html-documentation'));
30+
*
31+
* // Generating raw JSON documentation output
3732
* gulp.src('./index.js')
38-
* .pipe(documentation({
39-
* format: 'md'
40-
* }))
41-
* .pipe(gulp.dest('documentation'));
33+
* .pipe(gulpDocumentation('json'))
34+
* .pipe(gulp.dest('json-documentation'));
35+
*
4236
* });
4337
*
38+
* // Generate documentation for multiple files using normal glob syntax.
39+
* // Note that this generates one documentation output, so that it can
40+
* // easily cross-reference and use types.
41+
* gulp.task('documentation-multiple-files', function () {
4442
*
45-
* // documentation with JSON output, default filename API.md and custom Documentation instance
46-
* var documentation = require('gulp-documentation'),
47-
* $documentation = require('documentation');
48-
*
43+
* gulp.src('./src/*.js')
44+
* .pipe(gulpDocumentation({ format: 'md' }))
45+
* .pipe(gulp.dest('md-documentation'));
46+
*
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+
*
54+
* gulp.src('./src/*.js')
55+
* .pipe(gulpDocumentation('html', {}, {
56+
* name: 'My Project',
57+
* version: '1.0.0'
58+
* }))
59+
* .pipe(gulp.dest('html-documentation'));
4960
*
50-
* gulp.task('documentation-json', function () {
51-
* gulp.src('./index.js')
52-
* .pipe(documentation({
53-
* format: 'json'
54-
* }, $documentation))
55-
* .pipe(gulp.dest('documentation'));
5661
* });
57-
*
5862
*/
59-
module.exports = function (options) {
60-
options = options || {};
61-
62-
var docOptions = {
63-
github : !!(options.github || options.g),
64-
shallow: options.shallow || false
65-
};
63+
module.exports = function (format, options, formatterOptions) {
6664
var files = [];
67-
options.format = options.format || 'html';
68-
var formatter = documentation.formats[options.format];
65+
format = format || 'md';
66+
var formatter = documentation.formats[format];
6967
if (!formatter) {
7068
throw new Error('invalid format given: valid options are ' + Object.keys(documentation.formats).join(', '));
7169
}
@@ -75,14 +73,14 @@ module.exports = function (options) {
7573
}, function (cb) {
7674
documentation.build(files.map(function(file) {
7775
return file.path;
78-
}), docOptions, function(err, comments) {
79-
formatter(comments, {}, function (err, output) {
80-
if (options.format === 'json' || options.format === 'md') {
76+
}), options, function(err, comments) {
77+
formatter(comments, formatterOptions, function (err, output) {
78+
if (format === 'json' || format === 'md') {
8179
this.push(new File({
8280
path: options.filename || 'API.' + options.format,
8381
contents: new Buffer(output)
8482
}));
85-
} else if (options.format === 'html') {
83+
} else if (format === 'html') {
8684
output.forEach(function(file) {
8785
this.push(file);
8886
}.bind(this));

‎package.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
"url": "git@github.com:documentationjs/gulp-documentation.git"
2828
},
2929
"scripts": {
30-
"test": "eslint . && tap test/test.js"
30+
"test": "eslint . && tap test/test.js",
31+
"docs": "documentation readme index.js --section=API"
3132
}
3233
}

‎test-manual/multi/gulpfile.js

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,23 @@ var gulpDocumentation = require('../../'),
44
gulp.task('documentation', function () {
55

66
gulp.src('./src/*.js')
7-
.pipe(gulpDocumentation({format: 'md'}))
7+
.pipe(gulpDocumentation('md'))
88
.pipe(gulp.dest('md-documentation'));
99

1010
});
1111

1212
gulp.task('documentation-shallow', function () {
1313

1414
gulp.src('./src/*.js')
15-
.pipe(gulpDocumentation({ shallow: true,format: 'md' }))
15+
.pipe(gulpDocumentation('md',{ shallow: true }))
1616
.pipe(gulp.dest('md-documentation'));
1717

1818
});
19+
20+
gulp.task('documentation-name', function () {
21+
22+
gulp.src('./src/*.js')
23+
.pipe(gulpDocumentation('html', { shallow: true }, { name: 'My Project' }))
24+
.pipe(gulp.dest('html-documentation'));
25+
26+
});

‎test-manual/multi/md-documentation/API.md

Lines changed: 0 additions & 11 deletions
This file was deleted.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /