JSDoc 3 Template for AngularJS.
A JSDoc plugin and template for AngularJS, nothing else!
NOTE: the location of configure file and template directory has been moved with the release of 1.0.0 Please make changes accordingly for your gulp file.
- configure: Old:
node_modules/angular-jsdoc/conf.jsonNew:node_modules/angular-jsdoc/common/conf.json - template: Old:
node_modules/angular-jsdoc/templateNew:node_modules/angular-jsdoc/default
Blog: Sigh, AngularJS Documentation
- Right side TOC, table of contents, for navigation by Directives, Services, Controllers, etc
- Read and process @ngdoc tag
$ npm install jsdoc angular-jsdoc --save-dev
If you intend to use it with Grunt also execute:
$ npm install grunt-jsdoc --save-dev
// or you can run in command line
$ node_modules/jsdoc/jsdoc.js \
--configure node_modules/angular-jsdoc/common/conf.json \
--template node_modules/angular-jsdoc/angular-template \
--destination build/docs \
--readme README.md \
--recurse directives services
--tutorials tutorials
var shell = require('gulp-shell');
gulp.task('docs', shell.task([
'node_modules/jsdoc/jsdoc.js '+
'-c node_modules/angular-jsdoc/common/conf.json '+ // config file
'-t node_modules/angular-jsdoc/angular-template '+ // template file
'-d build/docs '+ // output directory
'./README.md ' + // to include README.md as index contents
'-r directives services' + // source code directory
'-u tutorials' // tutorials directory
]));
grunt.initConfig({
jsdoc: {
dist: {
src: ['directives', 'services'],
options: {
destination: 'build/docs',
configure: 'node_modules/angular-jsdoc/common/conf.json',
template: 'node_modules/angular-jsdoc/angular-template',
tutorial: 'tutorials',
readme: './README.md'
}
}
}
});
@ngdoc- specifies the type of thing being documented. See below for more detail.@scope- specifies the type of scope used by documented directive. Options aretruefor a new inherited scope,falsefor shared scope, and either{}orobjectfor isolate scope. if@scopeis provided without a value, a new shared scope will be assumed@priority- specifies the documented directive's priority@animations- specifies the animations that the documented directive supports@restrict- specifies how directives should be shown in the usage section. For example, for [E]lement, [A]ttribute, and [C]lass, use @restrict ECA@eventType emit|broadcast- specifies whether the event is emitted or broadcast
- Directive: map.js | Output
- Service: attr2-options.js | Output
- Controller: map-controller.js | Output
- Filter: custom-currency.js | Output
Currently, there are two templates built-in;
- default
- angular-template (Recommended)
To add your own template, please copy the angular-template directory to your own, then, make your own css, js, and html files.
Then, run the jsdoc.js command with your template. e.g.,
$ node_modules/jsdoc/jsdoc.js \
--configure node_modules/angular-jsdoc/common/conf.json \
--template node_modules/angular-jsdoc/my-template \
--destination build/docs \
--readme README.md \
--recurse directives services
If you want to share your template with others, please send a pull request after adding your template directory where angular-template directory is.
The following is the example of directory with explanation:
my-template
├── css
│ └── my.css # css used in layout.html
├── js
│ └── my.js # javascript used in layout.html
├── fonts
│ └── my.woff # font used in layout.html
├── html
│ ├── class.html # template used by layout.html
│ └── layout.html # layout file
└── publish.js # the main file that generate jsdoc
Currently the default angular-template does not come with custom fonts. If you would like to use a template like angular-template but with custom fonts, change the copyStaticFiles method in your publish.js:
angular-template/publish.js
// copy the template's static files to outdirvarcopyStaticFiles=function(){['css','js'].forEach(function(dirName){varfromDir=path.join(templatePath,dirName);varstaticFiles=fs.ls(fromDir,3);staticFiles.forEach(function(fileName){vartoDir=fs.toDir(fileName.replace(fromDir,path.join(outdir,dirName)));fs.mkPath(toDir);fs.copyFileSync(fileName,toDir);});});};to:
my-template/publish.js
// copy the template's static files to outdirvarcopyStaticFiles=function(){['css','js','fonts'].forEach(function(dirName){varfromDir=path.join(templatePath,dirName);varstaticFiles=fs.ls(fromDir,3);staticFiles.forEach(function(fileName){vartoDir=fs.toDir(fileName.replace(fromDir,path.join(outdir,dirName)));fs.mkPath(toDir);fs.copyFileSync(fileName,toDir);});});};MIT licence