照片来源:保罗乐园

创造美丽的文档10bet手机中文版

用typedoc和jekyll生成文档的指南10bet手机中文版

我们在Ironcore实验室的目标是使数字世界成为数据的更安全的地方,使开发人员能够为其应用程序增加世界级安全性而变得容易。该过程必须易于激发快速采用和广泛的集成。因此,优秀的文档,包括接合UI和易于遵循的指南,10bet手机中文版是我们的优先事项。

Irrorcore是一个由经验丰富的团队为中心的公司。我们希望自动化我们的文档,以保持最新,并尽可能最大限度地减少手动劳动力。10bet手机中文版此外,我们认为,特定于代码的文档应该生活在相关的代码存储库中,并以相同的方式维10bet手机中文版护我们维护代码。例如,应在拉出请求中与代码10bet手机中文版更新一起审查文档更新。

唉,代码生成10bet手机中文版的文档只需要我们到目前为止。生成的文档趋于较低。10bet手机中文版这很有用,但不足;用户还需要一个广泛的地图来指导它们到首先要查看的功能。优秀的用户指南需要经验丰富的开发人员编写更高级别的文档来指出方式,以及详细的文档,以帮助开发人员知道在哪里钻取。

从灵感开始

在Apple,我们曾经花过几周收集灵感。- Daniel Scrivner.

虽然存在重要方面条纹正方形启发了10bet手机中文版我们的文档,这两个服务都将其API文档与STARK UI Shift分开了他们的开发人员文档。脱节的经历让我们感到不满和困惑。

从类型签字生成文档10bet手机中文版

安装

经过仔细考虑生成文档的多个工具,Typedoc在其余部分上方作为最适合我们的需求。10bet手机中文版要安装typedoc,请运行以下内容:

// yarn //纱线添加typedoc --dev// npm //npm安装typedoc --save-dev

使用tdconfig.json配置typedoc

Typedoc可以通过以下两种方式之一10bet手机中文版导出文档:它可以使用HTML,样式和链接生成完整的网站,或者它可以导出JSON。我们希望我们的代码文档与其他文档和我们站点的其余部分集成,所以内置HTML模板不适用于我们。相反,我们生成了json,我们可以稍后再导入和格式化jekyll

在任何一种情况下,第一步是创建一个配置文件,这些文件在项目repo的根目录中生存。这个文件,tdconfig.json.,指定用于编译代码并生成文档的选项。10bet手机中文版它的格式类似于tsconfig.json.,任何类型签名项目所需的文件,以指定如何编译和服务项目。

有三个主要部分tdconfig.json.文件。一,是编译部分包括相同的编译器选项作为打字签字。接下来是包括排除部分。这些部分指定了Typedoc将记录哪些文件,并且不会。我们包含我们的全局定义文件和其他特定文件,并排除了我们的node_module.测试文件。

// tdconfig.json //{
“CompilerOptions”:{
“Moduleresolesolution”:“节点”,
“lib”:[
“ES6”,
“dom”
]
},
“包括”: [
“globals.d.ts”,
<包含应记录的文件的文件路径。>
“src / file1.ts”,
],
“排除”: [
“node_modules”,
“src / ** / *。test.ts”
]
}

产生

以JSON格式生成文档的最小命令是:

typedoc  -  json apidocs.json --mode modules --tsconfig tdconfig.json

命令行选项

Typedoc揭露了其他选项可以添加到上面提到的最小生成命令,以保持生成的JSON文件清洁和特定。以下是Ironcore使用的选项:

-  xcludeexternals.
**排除未明确导出的文件。
- 交换为止
**排除未明确导出的文件中的项目。
- Includedeclarations.
**在导出的文档中包含类型声明文件(**。d.ts)。10bet手机中文版

使用Jekyll模板

通过自动方法生成文档创10bet手机中文版建了与CodeBase紧密耦合并始终同步的参考材料,但他们到目前为止。

要设计令人愉快的开发人员体验,代码文档应与指南,教程,架构规范和其他长表格内容集成。10bet手机中文版Jekyll提供了一个解决方案,该解决方案合并经验丰富的开发人员和文档通过Ty10bet手机中文版pedoc生成的文档。

jekyll是一款与...集成的静态站点生成器GitHub页面方便地与JSON文件一起使用,然后可以通过变量访问site.data.并添加到以标记或HTML编写的静态模板。在我们的案例中,我们已经为我们的网站使用了Jekyll,因此我们可以轻松分享标题,页脚和样式。

这是一个简单的示例,用于在Jekyll模板中呈现JSON数据:

{%分配文档edfiles= site.data.apidocs%}##文件记录了documentedfiles%}中的文件%}
我们要记录的下一个文件名为:{{file.name}}。
{%endfor%}

目标是渲染导入的JSON中列出的导出的文件名。为此,我们会分配变量名称以表示所有JSON数据。Jekyll是有意其有的关于其文件结构,因此数据文件必须生活在内部_数据目录。从此,我们可以通过致电访问此数据site.data.然后是数据文件名。在示例中,路径apidocs.引用导入的JSON文件包含我们的原始文档数据。10bet手机中文版接下来,我们遍历生成的JSON输出中列出的每个文件名,在Jekyll模板中的部分标题中打印它。

包起来

10bet手机中文版即使实施过程复杂,文档应始终清晰。它应该提供定义的方法和指南,将路线图布置给用户入门的任何新系统或产品。

生成密集的功能文档非常容易,但制定10bet手机中文版一致和友好的开发人员体验需要额外照顾。Ironcore使用像Typedoc和Jekyll等工具,使系统简单且可管理,同时留下定制空间。

Ironcore的文档10bet手机中文版网站目前处于Beta模式,即将推出。释放后收到通知,注册我们的电子邮件列表我们会让你知道。

咸哈希

建筑物安全的提示,技巧,指针和透视图......

谢谢厄尼特纳帕特里克沃尔斯, 和鲍勃墙

麦迪逊soucie.

写道

慢性学习者。问题解决。探险家。创始工程师@bookclub。从持续改进中获得深刻的目的感。

咸哈希

建立安全,可测试,可维护的应用程序的提示,技巧,指针和透视图。Ironcore实验室安全与隐私的思考与观察。

麦迪逊soucie.

写道

慢性学习者。问题解决。探险家。创始工程师@bookclub。从持续改进中获得深刻的目的感。

咸哈希

建立安全,可测试,可维护的应用程序的提示,技巧,指针和透视图。Ironcore实验室安全与隐私的思考与观察。

中等的是一个开放的平台,17亿读者来寻找洞察力和动态的思维。在这里,专家和未被发现的声音相似地潜入任何主题的核心,并将新的想法带到表面上。学到更多

遵循对您有关的作家,出版物和主题,您将在您的主页和收件箱中看到它们。探索

如果您有一个故事来讲述,知识分享,或者提供提供的视角 - 欢迎回家。很容易和免费发布您对任何主题的思考。开始博客

获取媒体应用程序

一个按钮,称“在App Store上下载”,如果点击它将导致您到iOS App Store
一个按钮说'获得它,Google Play',如果点击它将导致您进入Google Play商店