angular-jsdoc-2

Angular-JSDoc

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.json New: node_modules/angular-jsdoc/common/conf.json
• template: Old: node_modules/angular-jsdoc/template New: node_modules/angular-jsdoc/default

Blog: Sigh, AngularJS Documentation

Features

• Right side TOC, table of contents, for navigation by Directives, Services, Controllers, etc
• Read and process @ngdoc tag

How Does It Look Like?

• angularjs-google-maps Documentation

Install

$ npm install jsdoc angular-jsdoc --save-dev

If you intend to use it with Grunt also execute:

$ npm install grunt-jsdoc --save-dev

Quick Start

With Command Line

// 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

Or, With Gulp

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
]));

Or, With Grunt

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'
      }
    }
  }
});

Tags Available

• @ngdoc - specifies the type of thing being documented. See below for more detail.
• @scope - specifies the type of scope used by documented directive. Options are true for a new inherited scope, false for shared scope, and either {} or object for isolate scope. if @scope is 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

Example

• Directive: map.js | Output
• Service: attr2-options.js | Output
• Controller: map-controller.js | Output
• Filter: custom-currency.js | Output

Customization

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 outdir
var copyStaticFiles = function() {
  ['css', 'js'].forEach(function(dirName) {
    var fromDir = path.join(templatePath, dirName);
    var staticFiles = fs.ls(fromDir, 3);
 
    staticFiles.forEach(function(fileName) {
      var toDir = 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 outdir
var copyStaticFiles = function() {
  ['css', 'js', 'fonts'].forEach(function(dirName) {
    var fromDir = path.join(templatePath, dirName);
    var staticFiles = fs.ls(fromDir, 3);
 
    staticFiles.forEach(function(fileName) {
      var toDir = fs.toDir( fileName.replace(fromDir, path.join(outdir, dirName)) );
      fs.mkPath(toDir);
      fs.copyFileSync(fileName, toDir);
    });
  });
};

Copyright

MIT licence