文档章节

Dgeni - 文档生成器

开源中国匿名会员
 开源中国匿名会员
发布于 2015/10/26 17:09
字数 1751
阅读 266
收藏 1

Dgeni - 文档生成器 Build Status

用 angular.js 和其他工程构建的 node.js 文档生成工具。

入门

试试看 Dgeni 示例项目。或者你在找的是用 AngularJS的例子。

观看 Pete 在 ng-europe 上关于 Dgeni 的演讲:

ScreenShot

安装

为了使用 Dgeni,你需要 node.js 和 npm 来安装 Dgeni 关联模块。从这里获取 node.js: http://nodejs.org/.

然后在你想生成文档的工程目录下安装 Dgeni:

npm install dgeni --save-dev

这会安装 Dgeni 和 Dgeni 相关联的所有模块。

运行 Dgeni

对于 Dgeni 本身,你并不用做太多配置。但是你必须配置 Packages,它包含了 ServicesProcessors 两部分。其中 Processors 将会实际负责将你的源文件转换成文档文件。

为了执行 processors 我们需要创建一个新的 Dgeni 实例,给它指定需要加载的 Packages 。然后只需要调用该实例的 generate() 方法。 generate() 方法将以异步方式调用 processors ,最后返回 Promise ,参数是生成的文档。

var Dgeni = require('dgeni');

var packages = [require('./myPackage')];

var dgeni = new Dgeni(packages);

dgeni.generate().then(function(docs) {
  console.log(docs.length, 'docs generated');
});

从命令行运行

Dgeni 通常会和生成工具一起使用,比如说 Gulp 或者 Grunt ,不过它也可以通过命令行来运行。

如果你把 Dgeni 安装在全局环境下,然后你可以从任何地方运行它:

npm install -g dgeni
dgeni some/package.js

如果 Dgeni 只被安装到了本地,那么你需要指明正确的安装路径:

npm install dgeni
node_modules/.bin/dgeni some/package.js

或者你可以通过 npm script 来运行:

{
  ...
  scripts: {
    docs: 'dgeni some/package.js'
  }
  ...
}

总之用法就是:

dgeni path/to/mainPackage [path/to/other/packages ...] [--log level]

你必须指定一个或多个 Dgeni Packages 的路径。以及设置(可选)日志级别。

Packages

ServicesProcessors,配置文件和模板被打包到 Package 中。Packages 还可以依赖别的 Packages。因此,你可以在已有的配置文件上,再定义你的自定义配置。

定义 Package

Dgeni 提供一个 Package 构造函数来创建新的 Packages。Package 实例中有用来注册 ServicesProcessors 的方法,以及可以设置 Processors 的属性:

var Package = require('dgeni').Package;
var myPackage = new Package('myPackage', ['packageDepencency1', 'packageDependency2']);

myPackage.processor(require('./processors/processor1'));
myPackage.processor(require('./processors/processor2'));

myPackage.factory(require('./services/service1'));
myPackage.factory(require('./services/service2'));

myPackage.config(function(processor1, service2) {
  service2.someProperty = 'some value';
  processor1.specialService = service2;
});

Services

Dgeni 大量使用 Dependency Injection (DI) 来实例化对象。那些需要用 DI 系统来实例化的对象必须提供一个 factory function,然后在 Package 中注册,或者作为 Processor,通过 myPackage.processor(factoryFn) 方式,或者作为 Service,通过 myPackage.factory(factoryFn) 方式。

定义 Service

factory function 的参数是需要能被 DI 系统找到的其它服务,或者是可以直接使用的实例。

car.js:

module.exports = function car(engine, wheels) {
  return {
    drive: function() {
      engine.start();
      wheels.turn();
    }
  };
};

这个例子中,我们定义了一个 car service,它依赖其它两个定义在别处的 services, enginewheels。注意,car service 并不关心这些依赖是怎样工作的,也不关心它们在哪里定义。 只要在它需要的时候 DI 系统能正确的提供即可。

被 factory function 返回的 car service 是一个对象,包含了一个方法, drive(),用来调用 enginewheels 的方法。

注册 Service

然后你需要将你的 Service 注册给 Package:

myPackage.js:

var Package = require('dgeni').Package;

module.exports = new Package('myPackage')
  .factory(require('./car'));

这样 car Service 就可以被其他的 Service,Processor 或者配置块使用了:

var Package = require('dgeni').Package;

module.exports = new Package('greenTaxiPackage', ['myPackage'])

  .factory(function taxi(car) {
    return {
      orderTaxi: function(place) { car.driveTo(place); }
    };
  })

  .config(function(car) {
    car.fuel = 'hybrid';
  });

Processors

Processors 是包含了 $process(docs) 方法的 Services。 processors 在 pipeline 中是按照顺序一个个执行的。每个 Processor 可以从前一个 Processor 获取生成的文档集合,并可以操作它,你可以插入新的文档或插入元数据。

Processors 可以设置一些属性,告诉 Dgeni 它们应该在管道的哪部分执行,以及如何验证 Processor 配置。

  • $enabled - 如果设为 false ,该 Processor 将不会被纳入 pipeline
  • $runAfter - 一组 Processor 名字字符串,它们在 pipeline 中必须出现 早于 该 Processor。
  • $runBefore - 一组 Processor 名字字符串,它们在 pipeline 中必须出现 晚于 该 Processor。
  • $validate - Dgeni 用于验证该 Processor 属性的约束对象 http://validatejs.org/

定义 Processor

你可以像定义 Service 一样定义 Processor:

myDocProcessor.js:

module.exports = function myDocProcessor(dependency1, dependency2) {
  return {
    $process: function (docs) {
        //... do stuff with the docs ...
    },
    $runAfter: ['otherProcessor1'],
    $runBefore: ['otherProcessor2', 'otherProcessor3'],
    $validate: {
      myProperty: { presence: true }
    },
    myProperty: 'some config value'
  };
};

注册 Processor

然后你要将 Processor 注册到 Package: myPackage.js:

var Package = require('dgeni').Package;

module.exports = new Package('myPackage')
  .processor(require('./myDocProcessor'));

异步 Processing

$process(docs) 方法可以使用同步或者异步方式调用:

  • 如果用同步方式,它将会返回 undefined 或者一组新的文档。如果返回的是一组新的文档,它将会取代之前的 docs
  • 如果用异步方式,它将会返回 Promise,最终处理结果将会是 undefined 或一组新的文档。如果返回的是 Promise,该 processor 告诉 Dgeni 它是以异步方式执行,这样 Dgeni 将会等待到该 promise 处理完毕,才会继续调用下一个 processor。

下面是一个使用异步 Processor 的例子

var qfs = require('q-io/fs');
module.exports = function readFileProcessor() {
  return {
    filePath: 'some/file.js',
    $process(docs) {
      return qfs.readFile(this.filePath).then(function(response) {
        docs.push(response.data);
      });
    }
  };

标准 Dgeni Packages

dgeni-packages repository 包含了许多预设 Processors - 从简单到复杂,以及 angular.js 特供版。这些 processors 在 Package 中被分为:

  • base - 包含有基本文件读写的基础 Processors,作为一个抽象的渲染 Processor 存在。

  • jsdoc - 依赖 base ,并添加了一些 Processors 和 Services,用于支持从代码注释中处理 jsdoc 样式标签。

  • nunjucks - 提供了 nunjucks 基本渲染引擎。

  • ngdoc - 依赖 jsdocnunjucks 并添加了额外的处理,适用于将 AngularJS 扩展用到 jsdoc。

  • examples - 依赖 jsdoc ,并提供了 Processors,用于将示例代码从 jsdoc 注释中抽取出来,并将它们提取成可以执行的文件。

  • dgeni - 支持将 dgeni Packages 文档化。

伪标记 Processors

你可以定义一些不处理任何事的,只作为处理流程阶段标记的 processor。你可以把它们应用到 $runBefore$runAfter 属性中,确保你的 Processor 能在正确的时间点被执行了。

在 dgeni-packages 的 Packages 中定义一些标记 processors。下面是一个顺序列表,Dgeni 会将它们按照这个顺序添加到 pipeline 的处理中去:

  • reading-files (定义在 base)
  • files-read (定义在 base)
  • parsing-tags (定义在 jsdoc)
  • tags-parsed (定义在 jsdoc)
  • extracting-tags (定义在 jsdoc)
  • tags-extracted (定义在 jsdoc)
  • processing-docs (定义在 base)
  • docs-processed (定义在 base)
  • adding-extra-docs (定义在 base)
  • extra-docs-added (定义在 base)
  • computing-ids (定义在 base)
  • ids-computed (定义在 base)
  • computing-paths (定义在 base)
  • paths-computed (定义在 base)
  • rendering-docs (定义在 base)
  • docs-rendered (定义在 base)
  • writing-files (定义在 base)
  • files-written (定义在 base)

配置文件

你可以在 Package 中配置 ServicesProcessors 或者通过对 Package 注册 Configuration Blocks 来适用设定。这有一些可以由 DI 系统注入到 ServicesProcessors 中的方法,你可以用来设定它们的属性。

注册配置块

你可以在 Package 上调用 config(configFn) 注册 Configuration Block

myPackage.config(function(readFilesProcessor) {
  readFilesProcessor.sourceFiles = ['src/**/*.js'];
});

© 著作权归作者所有

开源中国匿名会员

开源中国匿名会员

粉丝 78
博文 104
码字总数 113453
作品 2
徐汇
技术主管
私信 提问
和平之翼代码生成器 SMEU 版 3.2 Beta6 乌篷船已发布

目前和平之翼代码生成器SMEU 3.2版乌篷船正在Beta 6测试,有界面修正, 文档更新和联系信息更新。此版本支持Service,Dao组件扫描,SGS初始数据导入,多对多初始数据导入,一对多动态标签等先...

火箭船
2018/10/21
1K
4
RDIFramework.NET平台代码生成器V2.8发布-更新于2014-12-31(提供下载)

RDIFramework.NET平台代码生成器V2.8发布 更新于2014-12-31   RDIFramework.NET(.NET快速开发整合框架)框架做为信息化系统快速开发、整合的框架,其目的一至是给用户和开发者提供最佳的....

yonghu86
2018/06/26
0
0
和平之翼代码生成器 SMEU 版 3.2 Beta4 已发布

目前和平之翼代码生成器SMEU 3.2版乌篷船正在Beta 4测试, 此版本支持Service,Dao组件扫描,SGS初始数据导入,多对多初始数据导入,一对多动态标签等先进特性,新增在线文档:代码生成器技术...

火箭船
2018/10/10
584
2
LaineyC/blackdream

#BlackDream 文件生成器构建平台 ##机械重复性的工作如同黑色梦魇,同一个问题并不应该被解决两次。 ##项目介绍 网上的代码生成器形形色色五花八门,功能也很强大,甚至某些代码生成器能够一...

LaineyC
2016/09/20
0
0
和平之翼代码生成器SMEU Swing单机版提供二进制jar包下载

新近归并的和平之翼代码生成器SMEU Swing单机版提供二进制jar包下载。包括1.1版和1.6版的jar包。都是在jdk 1.8下编译的,装好java双击jar即可运行。 和平之翼代码生成器SMEU Swing单机版,是...

火箭船
2018/10/27
2
0

没有更多内容

加载失败,请刷新页面

加载更多

大厂面试经:高频率JVM面试问题整理!

JVM(Java虚拟机)简单来说就是运行Java代码的解释器,作为螺丝钉程序员JVM其实了解下就差不多啦,不懂JVM内部细节照样能写出优质的代码!但是一到造火箭、飞机的场景(面试)不懂JVM的你,会...

架构文摘
25分钟前
7
0
thinkphp5.1学习过程五——request

<?phpnamespace app\index\controller;//use \think\facade\Request;use \think\Request;/** * Class Demo3 * @package app\index\controller * 正常情况下,控制器不依赖......

大海yht
35分钟前
6
0
DB2 sequence 操作

操作DB2 下 sequence seqName db2数据库一般seq还是比较大的,但是程序在调用的时候还是不可避免的有一些bug, 下面是对于seq一些简单的操作,也作为工作的一些记录 1、命令行取sequence se...

飞雪无痕
今天
7
0
《吊打面试官》系列-秒杀系统设计

你知道的越多,你不知道的越多 点赞再看,养成习惯 GitHub上已经开源 https://github.com/JavaFamily 有一线大厂面试点脑图和个人联系方式,欢迎Star和指教 絮叨 之前写了很多Redis相关的知识...

敖丙
今天
15
0
Qt编写气体安全管理系统11-数据打印

一、前言 在各种软件系统中,数据打印也是常用的功能之一,一般来说会对查询的数据结果导出到excel,还会对查询的数据结果直接打印,在Qt中提供了打印机类QPrinter,在printsupport组件中,可...

飞扬青云
今天
5
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部