angular-jsdoc

JsDoc Plugin and Template for AngularJs

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

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 truefor a new inherited scope, falsefor shared scope, and either {}or objectfor 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

Example

Customization

Currently, there are two templates built-in;

  • default
  • angular-template (Recommended)

To add your own template, please copy the angular-templatedirectory to your own, then, make your own css, js, and html files.
Then, run the jsdoc.jscommand 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-templatedirectory 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 copyStaticFilesmethod 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

Repository

https@github.com:allenhwkim/angular-jsdoc


上一篇:prepush-hook
下一篇:number-to-locale-string

相关推荐

  • 高级 Angular 组件模式 (3b)

    03b Enhance Components with Directives 原文: Enhance Components with Directives(https://blog.angula...

    3 年前
  • 高级 Angular 组件模式 (3a)

    03a Communicate Between Components Using Dependency Injection 原文: Communicate Between Components ...

    3 年前
  • 问道Angular——Angular设置别名alias

    设置别名   在根目录下tsconfig.json中添加baseUrl和paths 访问环境变量   添加了@env别名,以便能够import { environment } fro...

    2 年前
  • 问道Angular——Angular刷新当前页面

    onSameUrlNavigation   从angular5.1起提供onSameUrlNavigation来支持路由重新加载。、   有两个值'reload'和'ignore'。

    2 年前
  • 问道Angular——APP_INITIALIZER

    概述   有时需要在加载应用之前运行代码,有时希望暂停应用初始化,直到完成某些限制之后再执行。APPINITIALIZER令牌可以完成这项操作。 APPINITIALIZER是一个函数,在应用改程...

    2 年前
  • 针对angular分页插件tm.pagination二次触发问题三种解决方案

    今天在开发个人博客的时候,需要对列表进行分页操作,因为整体使用的是AngularJs,所以分页插件也就选择了AngularJs pagination.js。可是在调试的时候发现的非常恶心的事情,在加载...

    9 个月前
  • 都 9012了,该选择 Angular、React,还是Vue?

    转载请注明出处:葡萄城官网(https://www.grapecity.com.cn/),葡萄城为开发者提供专业的开发工具、解决方案和服务,赋能开发者。 139239201904181526...

    1 年前
  • 通过框架设计理解react、angular、vue区别

    前言 我们已经通过学习掌握了vue.js这个渐进式的JavaScript 框架,并且大致知道了React、Angular和Vue的区别,那么如何对这三个框架进行深层次的分析,更好地区分它们呢?我们...

    8 个月前
  • 通过框架设计理解React、Angular、Vue区别

    前言 我们已经通过学习掌握了vue.js这个渐进式的JavaScript 框架,并且大致知道了React、Angular和Vue的区别,那么如何对这三个框架进行深层次的分析,更好地区分它们呢?我们...

    8 个月前
  • 走进AngularJs之过滤器(filter)详解

    过滤器(filter)正如其名,作用就是接收一个输入,通过某个规则进行处理,然后返回处理后的结果。主要用在数据的格式化上,例如获取一个数组中的子集,对数组中的元素进行排序等。

    3 年前

官方社区

扫码加入 JavaScript 社区