查看原文
其他

使用 Zeal 打造属于自己的文档

Season Java后端 2020-08-20

前言

技术博文征文比赛进行中,人人都可以参与,具体参与方式点击此链接:第一届技术博文征文活动开启!,本博文作者「Season」,如果喜欢本篇文章,可以通过收藏、转发、点赞、留言得方式支持作者。

作为一名程序开发者,翻查文档成为了每天都必须去做的事情。然而,由于使用到的知识和工具不相同,所以几乎每次都需要重新打开官网的文档进行搜索,而且不同知识和工具的文档还需要切换浏览器标签来浏览,十分不方便。再进一步,我们工作中,所用到的一些账号、密码以及日常的一些小知识点,如果归纳总结之后,可能也只是放在 word 或者 txt 里面,查阅也是比较不方便的。

那么有没有一个工具,即可以让我们方便查阅文档,又可以把自己日常用到的资料存起来的工具呢,下面就来介绍一下 Zeal 这一离线文档工具。

Zeal 简介

Zeal 是一款免费的离线文档软件,能够让开发者更加便捷地查阅api文档。目前该软件有 windows、mac 以及 linux 版本,内部有超过 200 个文档,涵盖了几乎所有程序开发用到的库、框架以及语言,是一款十分实用的软件。

Zeal官网:zealdocs.org/

Zeal下载:zealdocs.org/download.html

下载安装完成之后,界面上是看不到任何的文档的,因为需要去下载文档(Zeal 中文档的格式称为 Docsets)。在首页上面按下 Docsets 或者 Tools -> Docsets,选择你想要的文档进行下载,下载完成后就可以看到你所需要的文档了。

除了在 Zeal 的官网上面下载 Docsets 之外,还能通过 Add Feed 来添加。国外有热心的开发者收集了一个Docsets 集合(zealusercontributions.now.sh),我们只需要点开自己需要的 Docsets,复制 xml 地址到 Add Feed 里面,就可以对应下载 Docsets 了。

下载好自己需要的 Docsets 之后,日常就可以在工作中使用离线文档进行工作了。日常使用过程中,有几点需要注意:

  • Zeal 原理是打开 html 的页面,所以它相当于一个浏览器,尽量养成定时关闭不用文档的习惯

  • Zeal 能够设置打开的快捷键,设置了之后就能快速打开 Zeal 查阅文档

  • Zeal 左上角具备搜索功能,在前面输入“文档名称:内容”就可以对指定的文档进行搜索

Zeal 创建自己专属的文档项目

经过上面的步骤后,这个文档系统已经可以很好地为我们日常开发服务了,但是除了下载常用的 api 文档之外,能不能编写我们自己的文档呢?

Zeal 官方写了一个教我们如何去编写自己的 Docsets 的文档(https://kapeli.com/docsets),但是该文档写得比较简单,并且没有详细地操作指引,操作起来比较复杂。

经过实验之后,Zeal 的 Docsets 其实是 html 的集合,那么我们可以先用文档工具,生成一些静态的 html 文档。然后通过 Docsets 官方提供的 Docsets 生成器来把 html 生成 Docsets,这样就可以生成出属于我们自己的 Docsets 了。

合适的文档生成器

目前各种开发语言都有文档生成器,我比较熟悉的 Node.js 生成器就有数十个像 Gitbook、Docsify、Vuepress 等等。但是并不是每一个都适合用来制作 Docsets,举个例子:

Docsify 是一个很棒的生成器,但是用于 Docsets 的话就会有问题。原因是因为 Docsify 是通过 js 读取 Markdown 来实现的,而 Zeal 内部是一个浏览器,并没有静态服务器,所以制作出来的 Docsets 会出现跨域的问题。

最终我选择了使用 Gitbook 来制作 Docsets,它能生成静态的 Html 文件,并且能够通过本地双击打开,能够跟 Zeal 完美融合。

编写文档

确定了使用 Gitbook 之后,先安装 Gitbook:npm install gitbook-cli -g

然后,使用 Gitbook 创建项目:gitbook init

创建完之后,会看到如下目录结构:

├── README.md├── SUMMARY.md├── chapter1│ ├── README.md│ ├── section1.1.md│ └── section1.2.md└── chapter2 └── README.md

创建完成之后,通过命令 gitbook serve 即可看到文档的样式:

接下来就是每个开发者根据自己的需要,编写自己的 markdown 文件和修改 SUMMARY.md。由于文档是离线的,所以不用担心会被其他人盗取,可以把日常用到的账号密码、代码片段、常用的资料都分类写进去。

写完之后,通过命令 gitbook build 生成 html 文件。生成后会见到一个 _book 的目录,所有的 html 文件都在里面,这样文档就算编写完成了。


把 HTML 生成 Docsets

有了文档对应的 html 之后,需要把 html 生成 Docsets。我使用 Node.js 生成,在 npm 上面找了一个叫 docset-generator 的插件。通过以下代码,即可生成对应的 Docsets:

let DocSetGenerator = require("docset-generator").DocSetGenerator;let docSetGenerator = new DocSetGenerator({ destination: "./output/", name: "Season", documentation: "./personal-doc/_book", icon: './icon.png', entries: [ // entries 可以设置 Docsets 的分类,一般一个分类对应一个 html { name: "个人资料", type: "Guide", path: "./index.html" }, ... ]});docSetGenerator.create();

这里我把 Gitbook 和 docset-generator 整合到一个项目中,通过 npm-run-all 插件,先调用 Gitbook 生成 html,然后再生成 Docsets:

..."scripts": { "start": "gitbook build ./personal-doc && node index.js"},...

生成完之后,将会得到一个 XXX.docsets 的文件夹,接下来就是最后的一步,把这个文件夹放进 Zeal 里面。

在 Zeal 里面有一个叫 docsets 的文件夹,进去之后会看到下载的 docsets 都在里面,把刚刚生成的 docsets 放进去,重启一下 Zeal 就可以看到自己的文档了。

结语

以上是我在工作过程中,根据自己的开发习惯所做出来的一个小文档,如果大家有其他方便的工具,可以一起讨论一下,有任何问题欢迎留言。

1. 第一届技术博文征文活动开启!

2. 一键脱衣的 AI 软件 ?

3. 前端面试常问哪些问题?

4. Windows Terminal 预览版开放下载!

    您可能也对以下帖子感兴趣

    文章有问题?点此查看未经处理的缓存