如何为开源仓库文档添加示例代码

大海蓝莺IM 2022-09-27 20:27

开源，把代码公开出来就够了吗？不，还是要有文档。

蓝莺IM新文档中心上线，不仅增加了多语言支持，文档中的示例直接关联了开源仓库的代码。

为Gitbook文档添加示例代码的功能就是通过这个插件（lanying-code-snippet）实现的，如果你的项目文档是通过 Gitbook 创建，可以玩玩。

目前，蓝莺IM国际化基本完成，官网、文档中心、控制台和DemoAPP（安卓&iOS）均已增加多语言支持，欢迎观摩👏🏻

作者 | 大海

编辑 | 小蓝会聊天

“源码之前，了无秘密。”

跟团队讨论起开源仓库和文档，当我说出这句话的时候，原本期待的赞同并没有出现，而是一阵沉默。我忽然好像明白了什么。

没记错的话，这句话是侯捷老师在《STL源码解析》里说的。最开始看到的时候，我还处在对 C++ 的热爱中，对《Effective C++》《More Effective C+++》爱不释手。你没猜错，后面后面这两本书也都是侯捷老师翻译的，Scott Meyers 所著。

现在说起来，那时候微软还通过 MFC 框架在 C++ 领域大杀特杀，一转眼十几年过去，前几天看到的新闻是 Azure CTO 开始呼吁停止使用 C/C++ 开发新项目而改用 Rust了。

那时候也流行折腾代码，但凡遇到一个项目，第一反应就是把源码下载下来，运行调试把玩一番。当然有一点也不得不提，就是很多开源项目的文档也不完全，阅读源码是了解一个项目最高效准确的方式。多种原因交织之下，遇到的问题很多也是靠通过源码分析来定位解决。实际上，互联网服务线上问题的解决，也是如此。

所以「源码之前，了无秘密」就是提醒我们，有了代码啥都不怕。

然而技术的发展就像大河东流，越宽的水面越流得缓慢，也越势不可挡。就像我们之前在《过去的十五年，我们怎样做 IM？》里所说，软件开发已经进入了云服务时代，现在流行的是使用组件和 API 服务，自然代码就看得少了，文档也变得越来越重要。

言归正传。

在蓝莺IM DemoAPP刚刚开源的一段时间，我们的文档并不完善。这一方面是由于产品仍在快速迭代，文档的更新维护会比源码慢半拍，另一方面也是因为我们内心仍然会想，应用层的代码很简单并且已经开源，开发者直接使用开源仓库根据 Demo 操作即可找到示例，比文档要方便多了。

事实并非完全如此，虽然最终开发者仍会运行起 Demo 工程，但一个顺手的文档仍然是开始接触项目和解决问题时候的有力支持。

这便是我们开发这个Gitbook插件的主要原因。通过插件的方式，可以在 Gitbook 文档中的 API 说明里需要示例的地方，直接显示对应开源仓库中的使用代码和链接。

下文是详细介绍，如果暂时用不到，可以进入 Github 先 Fork&Star 收藏：

LCS（Lanying Code Snippet）：

https://github.com/maxim-top/gitbook-plugin-lanying-code-snippet

Lanying Code Snippet 介绍

Gitbook 可以将 markdown 文档转换成 html 页面，LCS 是 Gitbook 插件，在转换的过程中根据标记来补充页面内容。

也就是说，只要在 markdown 文件中插入带有仓库名称、类名和函数名的标签，LCS 插件据此来搜索 Github 仓库，在标签位置插入调用这个函数的代码块和github 链接。

LCS 搜索代码时使用的是 joern，一个可以分析代码和二进制的开源工具。通过预先分析源码仓库生成代码数据库，方便在读到文档标签时进行快速搜索。目前已支持C/C++/Java/Javascript/Objective-C 语言。

例如使用标签

 {% lanying_code_snippet 
   repo="lanying-im-web", 
   class="userManage", 
   function="asyncRegister" %}{% endlanying_code_snippet %}

，可以生成下面的代码块：

基本步骤只需四步：

要使用 Gitbook 来管理文档，需要安装 Gitbook；
使用自动文档生成工具，例如 doxygen、AppleDoc 等，从代码注释中生成 markdown（建议）；
配置 Lanying Code Snippet 插件；
运行 Gitbook 生成工具，生成最终文档；

详细安装过程如下：

1. 安装 Gitbook

1.1 安装 Node.js，推荐版本v16.17.0, 在此页面下载对应系统的安装包；

1.2 安装 Gitbook：

    npm install gitbook-cli -g

1.3 更新依赖库graceful-fs的版本：

cd `npm root -g`/gitbook-cli/node_modules/npm/node_modules
npm install graceful-fs@4.2.0 --save

2. 安装插件依赖

2.1 安装 JDK 11：

curl -s "https://get.sdkman.io" | bash && \
source "/Users/zoujinhai/.sdkman/bin/sdkman-init.sh" && \
sdk install java 11.0.16-amzn

2.2 安装 joern：

curl -L "https://github.com/joernio/joern/releases/latest/download/joern-install.sh" -o joern-install.sh && \
chmod u+x joern-install.sh && ./joern-install.sh

2.3 安装xcode 11 （要引用的代码仓库使用 Objective-C 语言时需要安装）

点击此链接下载Xcode 11，并解压，然后将得到的xcode.app文件夹复制到 /Applications 目录：

2.4 安装 llvm2cpg （要引用的代码仓库使用 Objective-C 语言时需要安装）

点击llvm2cpg，下载到可执行目录，并增加可执行权限：

2.5 在Gitbook book.json里增加如下插件, 然后运行 gitbook install。第一次可能会失败，如果失败需要再执行一次 gitbook install。

{ "plugins": ["lanying-code-snippet"] }

3. 配置 LCS

配置格式为：

{
    "plugins": [
        "lanying-code-snippet"
    ],
    "pluginsConfig": {
        "lanying-code-snippet": {
            "showLink": true,
            "reindent": true,
            "maxLine": 20,
            "maxSnippetCount": 10,
            "repositories": [
                {
                    "name":"lanying-im-web",
                    "url":"https://github.com/maxim-top/lanying-im-web.git",
                    "branch":"master"
                },
                {
                    "name":"lanying-im-android",
                    "url":"https://github.com/maxim-top/lanying-im-android.git",
                    "branch":"master",
                    "cacheDir": "../cache/lanying-im-android"
                }
            ]
        }
    }
}

配置说明：

showLink=true 是否在代码下显示github链接，默认为true
reindent=true 是否调整代码缩进. 默认为true
maxLine=20 每个代码片段的最大行数，默认为20
maxSnippetCount=10 最多显示多少个代码片段，默认为10
repositories 代码仓库信息
- repositories[*].url 仓库地址
- repositories[*].branch 仓库分支
- repositories[*].name 仓库名称，用于在标签里引用仓库
- repositories[*].cacheDir github仓库的本地缓存路径，如果不设置，会使用/tmp目录下的随机目录。如果使用Objective-C语言，cacheDir必须设置。

4. 生成文档

在 markdown 里插入下面格式的标签，然后使用

    gitbook build

或

    gitbook serve

就会将标签替换为相应的代码块：


{% lanying_code_snippet 
  repo="lanying-im-web",
  class="userManage",
  function="asyncRegister" %}{% endlanying_code_snippet %}

其中，repo 是仓库名称，需要与配置里的仓库名称一样。class是类名， function是函数名。

最后展现的效果，就是现在的蓝莺IM文档中心，好好玩吧 🎉🎉🎉

蓝莺IM开源计划（LIMOS）

截至 2021.08，蓝莺IM开源计划 LIMOS 已开源代码 163277 行。

以蓝莺IM开源项目为基础，我们也在打造一个专业的即时通讯技术社区，这便是我们的「蓝朋友计划」。

此计划将会邀请社区技术专家一起，共同分享关于即时通讯（IM）技术相关内容，欢迎持续关注，也欢迎自荐或推荐。