开源软件名称(OpenSource Name): jsBoot/gulp-jsdoc开源软件地址(OpenSource Url): https://github.com/jsBoot/gulp-jsdoc开源编程语言(OpenSource Language):
JavaScript
100.0%
开源软件介绍(OpenSource Introduction): THIS PROJECT IS DEPRECATED
jsdoc has recently had a major rewrite to v3.4 (support for JSX, ES6). This plugin is no longer being maintained and is incompatible with this change. It is recommended you use gulp-jsdoc3 instead: https://github.com/mlucool/gulp-jsdoc3
npm uninstall --save-dev gulp-jsdoc
npm install --save-dev gulp-jsdoc3
Note: gulp-jsdoc3 is not backwards compatible with this project (gulp-jsdoc). You will have to make minor configuration changes.
gulp-jsdoc
jsdoc plugin for gulp
TL;DR
Install gulp-jsdoc
as a development dependency:
npm install --save-dev gulp-jsdoc
Then, use it:
var jsdoc = require ( "gulp-jsdoc" ) ;
gulp . src ( "./src/*.js" )
. pipe ( jsdoc ( './documentation-output' ) )
API
jsdoc.parser(infos, name)
gulp . src ( "./src/*.js" )
. pipe ( jsdoc . parser ( infos , name ) )
. pipe ( gulp . dest ( './somewhere' ) )
Will process any files it has been fed, and generate a new vinyl JSON usable by the generator to produce actual documentation.
By default, the filename is 'jsdoc.json' unless overriden by the name parameter.
Note that if you feed the parser a README.md file, this file will be rendered and used as a long description for your package.
eg:
gulp . src ( [ "./src/*.js" , "README.md" ] )
. pipe ( jsdoc . parser ( infos , name ) )
. pipe ( gulp . dest ( './somewhere' ) )
The optional infos parameter is fed to jsdoc.
infos.name
Type: String
Default: ''
infos.description
Type: String
Default: ''
infos.version
Type: String
Default: ''
infos.licenses
Type: Array
Default: []
infos.plugins
Type: Array
Default: false
jsDoc plugins to use. Example: ['plugins/markdown']
jsdoc.generator(destination, template, options)
gulp . src ( "./somewhere/jsdoc.json" )
. pipe ( jsdoc . generator ( './destination' ) )
or directly from the parser pipe:
gulp . src ( [ "./src/*.js" , "README.md" ] )
. pipe ( jsdoc . parser ( infos , name ) )
. pipe ( jsdoc . generator ( './destination' ) )
By default, the generator uses the default template.
destination
Type: String
Default: ''
Where the documentation will be outputed.
If an infos object with a version / name was provided to the parser, these will be used in the final path.
template
You may optionnally specify a custom template, using the following syntax
{
path: 'path_to_template',
anyTemplateSpecificParameter: 'whatever'
}
As a courtesy, gulp-jsdoc bundles ink-docstrap templates, that you may use directly this way:
{
path : "ink-docstrap",
systemName : "Something",
footer : "Something",
copyright : "Something",
navType : "vertical",
theme : "journal",
linenums : true,
collapseSymbols : false,
inverseNav : false
}
See their site for more infos.
options
You may optionnally override default jsdoc behavior with this object:
{
showPrivate: false,
monospaceLinks: false,
cleverLinks: false,
outputSourceFiles: true
}
jsdoc(destination, template, infos, options)
gulp . src ( [ "./src/*.js" , "README.md" ] )
. pipe ( jsdoc ( './destination' ) )
... is simply a shortcut for
gulp . src ( [ "./src/*.js" , "README.md" ] )
. pipe ( jsdoc . parser ( ) )
. pipe ( jsdoc . generator ( './destination' ) )
Limitations
Only the parser is really using streams. While the generator will read from the result of the parser, it will also read and write templates files synchronously on its own.
There is nothing we can do about that, unless changing the jsdoc templating API entirely, and all existing templates...
Also, the following are currently not supported:
tutorials
sourcing configuration from jsdoc.conf files
If you have a use-case that you can't do with straight gulp in a better way, please say so.
License
MIT License
请发表评论