ng new ngx-dgeni-start

npm i dgeni dgeni-packages lodash --save-dev

npm i gulp --save-dev

├── docs/
│ ├── config/
│ │ ├── processors/
│ │ ├── templates/
│ │ ├── index.js│ ├── dist/

const Dgeni = require('dgeni');const DgeniPackage = Dgeni.Package;let apiDocsPackage = new DgeniPackage('ngx-dgeni-start-docs', [ require('dgeni-packages/jsdoc'), // jsdoc处理器
 require('dgeni-packages/nunjucks'), // HTML模板引擎
 require('dgeni-packages/typescript') // typescript包])

.config(function(log, readFilesProcessor, writeFilesProcessor) {
 // 设置日志等级
 log.level = 'info';
 // 设置项目根目录为基准路径 readFilesProcessor.basePath = sourceDir; readFilesProcessor.$enabled = false;
 // 指定输出路径
 writeFilesProcessor.outputFolder = outputDir;
})

.config(function(readTypeScriptModules) { // ts文件基准文件夹
 readTypeScriptModules.basePath = sourceDir; // 隐藏private变量
 readTypeScriptModules.hidePrivateMembers = true; // typescript 入口
 readTypeScriptModules.sourceFiles = [ 'app/**/*.{component,directive,service}.ts'
 ];
})

.config(function(templateFinder, templateEngine) { // 指定模板文件路径
 templateFinder.templateFolders = [path.resolve(__dirname, './templates')]; // 设置文件类型与模板之间的匹配关系
 templateFinder.templatePatterns = [ '${ doc.template }', '${ doc.id }.${ doc.docType }.template.html', '${ doc.id }.template.html', '${ doc.docType }.template.html', '${ doc.id }.${ doc.docType }.template.js', '${ doc.id }.template.js', '${ doc.docType }.template.js', '${ doc.id }.${ doc.docType }.template.json', '${ doc.id }.template.json', '${ doc.docType }.template.json', 'common.template.html'
 ]; // Nunjucks模板引擎，默认的标识会与Angular冲突
 templateEngine.config.tags = {
 variableStart: '{

以上是Dgeni配置信息，而接下来重点是如何对文档进行解析。

四、处理器

Dgeni 通过一种类似 Gulp 的流管道一样，我们可以根据需要创建相应的处理器来对文档对象进行修饰，从而达到模板引擎最终所需要的数据结构。

虽说 dgeni-packages 已经提供很多种便利使用的处理器，可文档的展示总归还是因人而异，所以如何自定义处理器非常重要。

处理器的结构非常简单：

module.exports = function linkInheritedDocs() { return { // 指定运行之前处理器
 $runBefore: ['categorizer'], // 指定运行之后处理器
 $runAfter: ['readTypeScriptModules'], // 处理器函数
 $process: docs => docs.filter(doc => isPublicDoc(doc))
 };
};

最后，将处理器挂钩至 dgeni 上。

new DgeniPackage('ngx-dgeni-start-docs', []).processor(require('./processors/link-inherited-docs'))

1、过滤处理器

Dgeni 在调用Typescript解析 ts 文件后所得到的文档对象，包含着所有类型（不管私有、还是NgOninit之类的生命周期事件）。因此，适当过滤一些不必要显示的文档类型非常重要。

const INTERNAL_METHODS = [ 'ngOnInit', 'ngOnChanges']module.exports = function docsPrivateFilter() { return {
 $runBefore: ['componentGrouper'],
 $process: docs => docs.filter(doc => isPublicDoc(doc))
 };
};function isPublicDoc(doc) { if (hasDocsPrivateTag(doc)) { return false;
 } else if (doc.docType === 'member') { return !isInternalMember(doc);
 } else if (doc.docType === 'class') {
 doc.members = doc.members.filter(memberDoc => isPublicDoc(memberDoc));
 } return true;
}// 过滤内部成员function isInternalMember(memberDoc) { return INTERNAL_METHODS.includes(memberDoc.name)
}// 过滤 docs-private 标记function hasDocsPrivateTag(doc) { let tags = doc.tags && doc.tags.tags; return tags ? tags.find(d => d.tagName == 'docs-private') : false;
}

2、分类处理器

虽然 Angular 是 Typescript 文件，但相对于 ts 而言本身对装饰器的依赖非常重，而默认 typescript 对这类的归纳其实是很难满足我们模板引擎所需要的数据结构的，比如一个 @Input()变量，默认的情况下 ts 解析器统一用一个 tags变量来表示，这对模板引擎来说太难于驾驭。

所以，对文档的分类是很必须的。

/**
* 对文档对象增加一些 `isMethod`、`isDirective` 等属性
*
* isMethod | 是否类方法
* isDirective | 是否@Directive类
* isComponent | 是否@Component类
* isService | 是否@Injectable类
* isNgModule | 是否NgModule类
*/module.exports = function categorizer() { return {
 $runBefore: ['docs-processed'],
 $process: function(docs) {
 docs.filter(doc => ~['class'].indexOf(doc.docType)).forEach(doc => decorateClassDoc(doc));
 }
 }; 
 /** 识别Component、Directive等 */
 function decorateClassDoc(classDoc) { // 将所有方法与属性写入doc中（包括继承）
 classDoc.methods = resolveMethods(classDoc);
 classDoc.properties = resolveProperties(classDoc); // 根据装饰器重新修改方法与属性
 classDoc.methods.forEach(doc => decorateMethodDoc(doc));
 classDoc.properties.forEach(doc => decoratePropertyDoc(doc)); 
 const component = isComponent(classDoc); const directive = isDirective(classDoc); if (component || directive) {
 classDoc.exportAs = getMetadataProperty(classDoc, 'exportAs');
 classDoc.selectors = getDirectiveSelectors(classDoc);
 }
 classDoc.isComponent = component;
 classDoc.isDirective = directive; 
 if (isService(classDoc)) {
 classDoc.isService = true;
 } else if (isNgModule(classDoc)) {
 classDoc.isNgModule = true;
 }
 }
}

3、分组处理器

ts 解析后在程序中的表现是一个数组类似，每一个文档都被当成一个数组元素。所以需要将这些文档进行分组。

我这里采用跟源文件相同目录结构分法。

/** 数据结构*/class ComponentGroup {
 constructor(name) { this.name = name; this.id = `component-group-${name}`; this.aliases = []; this.docType = 'componentGroup'; this.components = []; this.directives = []; this.services = []; this.additionalClasses = []; this.typeClasses = []; this.interfaceClasses = []; this.ngModule = null;
 }
}
module.exports = function componentGrouper() { return {
 $runBefore: ['docs-processed'],
 $process: function(docs) { let groups = new Map();
 docs.forEach(doc => { let basePath = doc.fileInfo.basePath; let filePath = doc.fileInfo.filePath; // 保持 `/src/app` 的目录结构
 let fileSep = path.relative(basePath, filePath).split(path.sep); let groupName = fileSep.slice(0, fileSep.length - 1).join('/'); // 不存在时创建它
 let group; if (groups.has(groupName)) { group = groups.get(groupName);
 } else { group = new ComponentGroup(groupName);
 groups.set(groupName, group);
 } if (doc.isComponent) { group.components.push(doc);
 } else if (doc.isDirective) { group.directives.push(doc);
 } else if (doc.isService) { group.services.push(doc);
 } else if (doc.isNgModule) { group.ngModule = doc;
 } else if (doc.docType === 'class') { group.additionalClasses.push(doc);
 } else if (doc.docType === 'interface') { group.interfaceClasses.push(doc);
 } else if (doc.docType === 'type') { group.typeClasses.push(doc);
 }
 }); return Array.from(groups.values());
 }
 };
};

但，这样还是无法让 Dgeni 知道如何去区分？因此，我们还需要按路径输出处理器配置：

.config(function(computePathsProcessor) {
 computePathsProcessor.pathTemplates = [{
 docTypes: ['componentGroup'],
 pathTemplate: '${name}',
 outputPathTemplate: '${name}.html',
 }];
})

五、模板引擎

dgeni-packages 提供 Nunjucks 模板引擎来渲染文档。之前，我们就学过如何配置模板引擎所需要的模板文件目录及标签格式。

接下来，只需要创建这些模板文件即可，数据源就是文档对象，之前花很多功夫去了解处理器；最核心的目的就是要将文档对象转换成更便利于模板引擎使用。而如何编写 Nunjucks 模板不再赘述。

在编写分组处理器时，强制文件类型 this.docType = 'componentGroup';；而在配置按路径输出处理器也指明这一层关系。

因此，需要创建一个文件名叫 componentGroup.template.html 模板文件做为开始，为什么必须是这样的名称，你可以回头看模板引擎配置那一节。

而模板文件中所需要的数据结构名叫 doc，因此，在模板引擎中使用 {$ doc.name $}来表示分组处理器数据结构中的 ComponentGroup.name。