内容简介:如何将Angular文档化?
这段时间写了十几个Angular小组件,如何将代码中的注释转换成漂亮的在线文档一直都让我有点头疼;更别说在企业级解决方案里面,如果没有良好的文档对阅读实在不敢想象。
下面我将介绍如何使用Dgeni生成你的Typescript文档,当然,核心还是为了Angular。
什么是Dgeni?
Dgeni是Angular团队开始的一个非常强大的NodeJS文档生成工具,所以说,不光是Angular项目,也可以运用到所有适用TypeScript、AngularJS、Ionic、Protractor等项目中。
主要功能就是将源代码中的注释转换成文档文件,例如HTML文件。而且还提供多种插件、服务、处理器、HTML模板引擎等,来帮助我们生成文档格式。
如果你之前的源代码注释都是在JSDoc形式编写的话,那么,你完全可以使用Dgeni创建文档。
那么,开始吧!
一、脚手项目
首先先使用angular cli创建一个项目,名也: ngx-dgeni-start 。
ng new ngx-dgeni-start
接着还需要几个Npm包:
-
Dgeni 文档生成器。
-
Dgeni Packages 源代码生成文档的dgeni软件包。
-
Lodash Javascript工具库。
npm i dgeni dgeni-packages lodash --save-dev
dgeni 需要gulp来启用,所以,还需要gulp相关依赖包:
npm i gulp --save-dev
二、文件结构
首先创建一个 docs/
文件夹用于存放dgeni所有相关的配置信息,
├── docs/ │ ├── config/ │ │ ├── processors/ │ │ ├── templates/ │ │ ├── index.js │ ├── dist/
config
下创建 index.js
配置文件,以及 processors 处理器和 templates 模板文件夹。
dist
下就是最后生成的结果。
三、配置文件
首先在 index.js
配置Dgeni。
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包 ])
先加载 Dgeni 所需要的包依赖。下一步,需要通过配置来告知dgeni如何生成我们的文档。
1、设置源文件和输出路径
.config(function(log, readFilesProcessor, writeFilesProcessor) { // 设置日志等级 log.level = 'info'; // 设置项目根目录为基准路径 readFilesProcessor.basePath = sourceDir; readFilesProcessor.$enabled = false; // 指定输出路径 writeFilesProcessor.outputFolder = outputDir; })
2、设置Typescript解析器
.config(function(readTypeScriptModules) { // ts文件基准文件夹 readTypeScriptModules.basePath = sourceDir; // 隐藏private变量 readTypeScriptModules.hidePrivateMembers = true; // typescript 入口 readTypeScriptModules.sourceFiles = [ 'app/**/*.{component,directive,service}.ts' ]; })
3、设置模板引擎
.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: '{$', variableEnd: '$}' }; })
以上是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
。
六、结论
如果有人再说 React 里面可以非常方便生成注释文档,而 Angular 怎么这么差,我就不同意了。
Angular依然可以非常简单的创建漂亮的文档,当然市面也有非常好的文档生成工具,例如: compodoc 。
最后,文章中所有源代码见 Github 。
以上所述就是小编给大家介绍的《如何将Angular文档化?》,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对 码农网 的支持!
猜你喜欢:- 觅道文档 v0.6.0 发布,在线文档系统
- 一个适合程序员的 Markdown 文档编辑和文档管理方案
- 【微服务】如何优雅的写文档(文档自动化swagger)
- 利用Python3内置文档资源高效学习及官方中文文档
- 什么是 API 文档工具?附带 6 款好用的 API 文档工具介绍
- VirAPI 接口文档导出功能上线,可分享并离线查看接口文档啦!
本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。
美团机器学习实践
美团算法团队 / 人民邮电出版社 / 2018-8-1 / 79.00元
人工智能技术正以一种超快的速度深刻地改变着我们的生活,引导了第四次工业革命。美团作为国内O2O领域领 先的服务平台,结合自身的业务场景和数据,积极进行了人工智能领域的应用探索。在美团的搜索、推荐、计算广告、风控、图像处理等领域,相关的人工智能技术得到广泛的应用。本书包括通用流程、数据挖掘、搜索和推荐、计算广告、深度学习以及算法工程6大部分内容,全面介绍了美团在多个重要方面对机器学习的应用。 ......一起来看看 《美团机器学习实践》 这本书的介绍吧!