/docs

LeanCloud Documentation

Primary LanguageCSSGNU Lesser General Public License v3.0LGPL-3.0

LeanCloud Documentation

Build Status devDependency Status Issue Stats Issue Stats

Gitter

LeanCloud 开发者文档

说明

这个项目是 LeanCloud 文档上的所有文档的 Markdown 格式的源码,最终将渲染成你在网站上看到的 HTML 文档

因此 Markdown 文件里部分链接写的是最终渲染后的链接,如果直接点击会发现 404 错误。

贡献

我们欢迎所有用户提交 PR 或 issue 为我们贡献或者修正错误,LeanCloud 衷心感谢您的贡献。

贡献方法及注意事项

  • fork 这个项目
  • npm install 安装相关依赖
  • 执行 grunt server 可以本地预览
  • 修改 /views 目录中的文档
    • /views 中是模板文件,会被编译为 /md 目录中对应的文档文件。
    • 模板支持嵌套,如 /viewsa.md 是可以被嵌套在 a.tmpl 中,方法参见下文 [一套模板多份渲染](#一套模板多份渲染)。
    • 相关图片放在 /images 目录中,引用格式为 ![图片文字说明](images/livekit-gifts.png)
    • 由于文档会经过 Nunjucks 和 AngularJS 渲染,当文档中需要显示 {{content}} 这种格式时,需要:
      • 在文档开头增加 {% set content = '{{content}}' %},如果没有声明 Nunjucks 会将其渲染为空白。
      • 在正文中加上 <span ng-non-bindable>{{content}}</span>,避免被 AngularJS 渲染。
  • 新增一个文档
    • 命名使用中划线和小写字母,如 livekit-android.mdquick-start-ios.md
    • 如需要,更新文档首页 templates/pages/index.html 和顶部导航菜单 templates/include/header.html
  • 修改文中标题或文件名称
    • 确认要修改的标题 h1-h6 或文件名称有没有被 /views/templates 目录下任何文件所引用,以免产生断链。
    • 系统自动生成的 h1-h6 标题的 id,会将所有空格、中西文标点替换为下划线,如 ## 调用 Console.log() 会生成 <h2 id="调用_Console_log__">,在引用时需要留意,包括大小写。
  • 提交修改并发起 Pull Request

内部贡献

为避免在所提交 PR 中出现与修改内容无关的 Merge pull request 的 commits,推荐使用以下流程提交 PR:

  1. 本地切换到 master 分支
  2. rebase
  3. 新建分支 new branch 进行修改
  4. 提交 PR,如有相关的 issue 在注释中增加 Fixes #???。问号为 issue 的编号。

合并 PR 时,如果 commits 历史不重要,可以选择 Squash and Merge 来合并,合并后删除相关的分支。

PR 合并后,要让改动最终生效还需要通过 Jenkins 执行 cn-avoscloud-docs-prod-ucloud 任务进行发布。

目录结构

├── README.md                          // 说明文档
├── archive                            // 已下线存档的文档,请勿更新
├── custom                             // 文档页面样式及 JavaScript 代码
├── images                             // 文档中引用的所有图片
├── md                                 // 临时目录(文档均为自动生成,因为不要修改)
├── dist                               // 编译之后生成的文件将会在此目录下
├── private                            // 未完成、未发布的文档临时保存在这里,以便让重建全站文档索引的系统任务忽略这些文件
├── react                              // 文档评论功能所需要用的 React 组件
├── server_public                      // 文档评论功能所需要用的 React 组件
├── templates                          // 文档网站的 HTML 页面模板
├── views                              // Markdown 格式文档的模板文件和源文件,使用时会被编译到 md 目录中
├── app.coffee
├── app.json
├── CHANGELOG.md                       // changelog 记录
├── circle.yml
├── CONTRIBUTING.md                    // 贡献指南
├── package.json
└── ...

预览

开发服务基于 Grunt,所以需要有 Nodejs 环境,通过 NPM 安装测试需要的依赖

安装 Grunt

$ sudo npm install -g grunt-cli

安装需要的依赖

$ npm install

本地启动一个 HTTP Server,然后打开浏览器访问 http://localhost:3000 即可

$ grunt server

版本更新

  • 请通过 grunt release 命令自动 bump package.json、自动打标签,请不要手动更新
  • 请按照 CONVENTIONS.md 的格式书写有意义的 commits,CHANGELOG.md 会被自动生成,请不要手动修改

一套模板多份渲染

有些文档的相似度非常高,所以可以使用一份模板,多分变量渲染的方式一次性生成多份文档,比如 「LeanEngine 指南」的文档就是这样生成的。这份文档分为三个运行时:Node.js、Python、云引擎 2.0。最终效果可见 LeanEngine (Node.js 环境)LeanEngine(Python 环境)。这类文档编写方式如下:

  • views 目录先编写一份「模板」(以 tmpl 作为扩展名),将文档的主体部分完成,将文档之间不一样的部分(比如不同语言的代码片段)使用:

    {% block <blockName> %}{% endblock %}
    

    括起来。可以参考 leanengine_guide.tmpl

  • views 目录里编写多份渲染变量(以 md 作为文件扩展名)。第一行表明自己继承哪个模板:

    {% extends "./<your-tmpl-file>" %}
    

    后续的内容就是用:

    {% block <blockName> %}<不同文档之间的差异>{% endblock%}
    

    来替换模板中存在的 block。可以参考 leanengine_guide-node.tmpl

  • 生成文档:使用下列命令会在 md 文件夹中生成最终的 md 文件:

    grunt nunjucks
    

    同样支持 grunt server 命令,该命令最终会执行 watch 插件,此时修改模板文件,或者变量文件都会自动重新生成最终的 md 文件(可能需要等待 2~4 秒)。

  • 记得将这种方式生成的 md 文件添加到 .gitignore 文件中,确保这类文件不会被提交。

注意:如果在模板中需要渲染 {{appid}} 这样的 AngularJS 变量,则必须在模板文件的最上方先定义好一个新变量,如 appid,其值为 '{{appid}}',例如:

{% set appid = '{{appid}}' %}
{% set appkey = '{{appkey}}' %}
{% set masterkey = '{{masterkey}}' %}

这样,在生成的 html 文档中,{{appid}} 才可以被正确渲染,否则,它会被替换为空值,原因是 nunjucks 在上下文中找不到该变量的定义。

其他常用的 nunjucks 模板方法 还有:

{# 这是注释,用 <!-- --> 无效 #}

{% if numUsers < 5 %}...{% endif %}
{% if i != "String" %}...{% endif %}
{% if users and showUsers %}...{% endif %}
{% if i == 0 and not hideFirst %}...{% endif %}
{% if (x < 5 or y < 5) and foo %}...{% endif %}

// 复用文档片断
{% macro ... %}
{% include ... %}

辅助工具

「一套模板多分渲染」的不同渲染文件编写起来比较困难,需要先从主模板上找到变量在对应到渲染文件,所以开发了一个简单的工具来简化这一步骤。使用方式如下:

  • 安装需要的依赖,该步骤只需要执行一次:

    npm install
    
  • 启动辅助工具的本地 webServer,使用以下命令:

    $ node server
    
  • 使用浏览器打开 http://localhost:3001,将会看到一个「选择模板」的下拉列表框,该列表框里会显示 views/<tmplName>.tmpl 的所有模板文件,文件名的 tmplName 部分是下拉列表框选项的名称。选择你需要编写的模板(比如 leanengine_guide)。

  • 你会看到模板文件被读取,其中所有 {% block <blockName> %}<content>{% endblock %} 部分的下面都会有一些按钮。这些按钮表示该「模板」拥有的不同「渲染」,也就是对应的 views/<tmplName>-<impl>.md 文件,文件名的 impl 部分是按钮的名称。

  • 点击对应的按钮,即可看到「渲染」文件中对应 block 的内容已经读取到一个文本域中,如果为空,表明该「渲染」文件未渲染该 block,或者内容为空。

  • 在文本域中写入需要的内容,然后点击保存,编写的内容就会保存到对应的「渲染」文件的 block 中。

  • 最后建议打开「渲染」文件确认下内容,没问题即可通过 grunt server 查看效果。当然整个过程打开 grunt server 也是没问题的,它会发现「渲染」文件变动后重新加载。

有问题请与 wchen@leancloud.rocks 联系。

License

LGPL-3.0