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

大海 蓝莺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 %}

,可以生成下面的代码块:

基本步骤只需四步:

  1. 要使用 Gitbook 来管理文档,需要安装 Gitbook;

  2. 使用自动文档生成工具,例如 doxygen、AppleDoc 等,从代码注释中生成 markdown(建议);

  3. 配置 Lanying Code Snippet 插件;

  4. 运行 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)技术相关内容,欢迎持续关注,也欢迎自荐或推荐。

© 2019-2023 美信拓扑 | 官网 该文件修订时间: 2023-08-09 14:48:15

results matching ""

    No results matching ""