如何将Angular文档化？

栏目: 编程语言 · AngularJS · 发布时间: 6年前

内容简介：如何将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文档化？》，希望对大家有所帮助，如果大家有任何疑问请给我留言，小编会及时回复大家的。在此也非常感谢大家对 码农网 的支持！

查看所有标签

猜你喜欢:

本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。

码农书籍
Mastering Regular Expressions, Second Edition

Mastering Regular Expressions, Second Edition

Jeffrey E F Friedl / O'Reilly Media / 2002-07-15 / USD 39.95

Regular expressions are an extremely powerful tool for manipulating text and data. They have spread like wildfire in recent years, now offered as standard features in Perl, Java, VB.NET and C# (and an......一起来看看 《Mastering Regular Expressions, Second Edition》 这本书的介绍吧!

码农工具
URL 编码/解码
URL 编码/解码

URL 编码/解码

XML、JSON 在线转换
XML、JSON 在线转换

在线XML、JSON转换工具

HEX CMYK 转换工具
HEX CMYK 转换工具

HEX CMYK 互转工具

  • New
  • 文章
  • 话题
  • 教程
    • 关注 码农网 公众号
    版权所有，保留一切权利！© 2018-2024 码农网 粤ICP备17054400号-3