chinclubi / angular-jsdoc

AngularJS Template/Plugin for JSDoc 3.

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

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/default \
  --destination build/docs \
  --readme README.md \
  --recurse directives services

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

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',
        readme: './README.md'
      }
    }
  }
});

Or, With NodeJS

var angularJsdoc = require('angular-jsdoc');
angularJsdoc(['my-source1', 'my-source2']);


// or with options
angularJsdoc('sample-codes', {
  template: 'default',
  destination: 'default/docs',
  readme: "sample-codes/README.md"
}, function(output) {
  console.log('output', output);
});

Specification

angularJsdoc(sourceDirectory, options, callback)

• sourceDirectory: list of source code directories. e.g. ['dir1', 'dir2']

• options:

  • command: jsdoc.js command Default: node_modules/jsdoc/jsdoc.js
  • configure: The path to the configuration file. Default: angular-jsdoc/common/conf.json
  • destination: The path to the output folder. Default: ./docs
  • template: The path to the template to use Default: angular-jsdoc/default
  • readme: The path to the project's README file. Default: 'README.md'

• callback: callback function with output parameter. e.g., function(output) {console.log(output)}

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

To add your own template, please copy the default 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 default 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

Copyright

MIT licence