搜索

[23483] 2015-01-13_Github是如何使用Github来处理Github文档的

文档创建者：s7ckTeam
浏览次数：5
最后更新：2025-01-18
2015-01-13_Github是如何使用Github来处理Github文档的 G i t h u b   是 如 何 使 用   G i t h u b   来 处 理   G i t h u b   文 档 的 L i n u x 中 国   2 0 1 5 - 0 1 - 1 3 提 供 书 写 良 好 的 文 档 ， 可 以 帮 助 人 们 理 解 并 很 好 地 使 用 你 的 项 目 ， 而 且 人 们 还 能 够 很 容 易 地 参 与 你 的 项 目 并 作 出 贡 献 ， 但 这 仍 不 够 。 基 于 文 档 服 务 的 底 层 系 统 能 够 使 任 何 人 — — 包 括 你 或 你 的 团 队 写 文 档 更 轻 松 。 对 于 文 档 的 编 写 ， 最 大 的 难 点 不 是 如 何 配 置 工 具 ， 或 者 要 弄 清 楚 怎 么 部 署 更 新 ， 而 在 于 如 何 斟 词 酌 句 。 G i t H u b 文 档 制 作 团 队 的 成 员 有 着 丰 富 的 工 作 背 景 ， 包 括 使 用 原 生 的 基 于 X M L 的 写 作 工 具 ， 以 及 复 杂 的 C M S 系 统 。 但 我 们 并 不 想 使 用 那 些 工 具 ， 因 此 我 们 花 费 了 大 量 时 间 和 精 力 来 配 置 我 们 自 己 的 文 档 制 作 流 程 和 工 作 计 划 。 以 前 我 们 也 谈 论 过 怎 么 使 用 G i t H u b 构 建 G i t H u b ； 如 下 就 是 我 们 怎 样 使 用   G i t H u b   P a g e s   每 月 向 数 百 万 读 者 提 供   我 们 的 G i t H u b 帮 助 文 档 。 我 们 以 前 的 流 程 几 个 月 前 ， 我 们 把 帮 助 系 统 的 站 点 从 自 建 的 R a i l s 程 序 迁 移 到 了   G i t h u b   P a g e s   上 的 J e k y l l 。 之 前 我 们 的 帮 助 系 统 需 要 两 个 相 互 独 立 的 项 目 仓 库 ： 负 责 运 维 网 站 、 管 理 网 站 资 源 ， 以 及 实 现 文 档 搜 索 的   R a i l s   应 用 程 序 由 一 大 堆   M a r k d o w n   文 件 组 成 的 网 站 具 体 内 容 我 们 的   R a i l s   应 用 程 序 托 管 在 一 个 第 三 方 平 台 上 。 随 着 代 码 的 不 断 更 新 升 级 ， 我 们 将 它 部 署 在 了   H u b o t a n d   C h a t o p s   ， 这 些 都 是 我 们 在 维 护 G i t h u b   主 站 的 闲 暇 之 余 完 成 的 。 我 们 正 常 的 撰 写 流 程 可 能 是 这 个 样 子 的 ：
当 有 新 特 征 开 发 出 来 的 时 候 文 档 团 队 首 先 编 写 好 文 档 内 容 创 建 一 个 新 的   i s s u e   去 追 踪 这 个 特 征 当 文 档 更 新 完 毕 一 切 就 绪 之 后 ， 我 们 会 发 起 一 个   p u l l   r e q u e s t   去 迭 代 更 新 文 档 内 容 。 P R   发 起 成 功 后 ， 我 们 会 使 用   @   方 式 提 醒 团 队 （ 比 如   @ g i t h u b / d o c s   ） 并 会 让 队 友 们 审 查 一 下 我 们 的 内 容 。 当 这 个 特 征 开 发 完 毕 已 经 上 线 的 时 候 ， 我 们 会 合 并 之 前 创 建 的   P R 。   使 用 w e b h o o k 能 够 帮 助 我 们 在 内 容 仓 库 快 速 激 活 我 们 部 署 的 R a i l s   应 用 程 序 。 w e b h o o k   承 担 了 负 责 更 新 数 据 库 的 任 务 。 下 面 是 一 个 简 单 的 示 例 ， @ n e v e r e t a n d @ b e r n a r s 给 我 们 展 示 了 一 下 我 们 正 常 的 工 作 流 程 ： 使 用 p u l l   r e q u e s t s 进 行 工 作 很 有 意 思 ， 因 为 它 正 好 和 我 们 团 队 使 用 的   G i t h u b 工 作 流 程 是 一 致 的 。 并 且 M a r k d o w n   的 语 法 能 让 我 们 快 速 高 效 地 表 达 出 新 特 性 的 独 到 之 处 ， 所 以 我 们 写 文 档 时 ， 对 它 情 有 独 钟 。 然 而 ， 我 们 的   R a i l s   程 序 维 护 起 来 相 当 麻 烦 ： 由 于 我 们 的 主 机 是 外 部 托 管 ， 所 以 我 们 需 要 工 程 ， 运 维 和 安 全 团 队 的 专 业 人 员 实 时 监 控 站 点 运 行 状 况 ， 并 能 及 时 处 理 突 发 事 件 。 我 们 的 文 档 团 队 并 不 能 方 便 的 预 览 内 容 的 变 化 。 虽 然 我 们 使 用   M a r k d o w n   编 写 内 容 ， 可 以 实 时 预 览 ， 但 是 我 们 仍 然 需 要 配 置 一 个 本 地 的   R a i l s   应 用 服 务 去 运 行 脚 本 将 内 容 导 入 到 数 据 库 中 然 后 观 察 其 在 网 站 上 的 最 终 效 果 。 虽 然 我 们 不 断 的 调 整   R a i l s   服 务 器 设 置 ， 而 用 户 发 起 请 求 后 响 应 速 度 依 然 缓 慢 。 这 是 因 为   H T M L   页 面 是 动 态 生 成 的 ， 需 要 对 数 据 库 进 行 频 繁 访 问 ， 即 便 运 用 更 为 强 大 的 缓 存 策 略 ， 依 然 收 效 甚 微 。 我 们 意 识 到 ， 其 实 我 们 可 以 做 得 更 好 。 我 们 的 新 流 程 当   J e k y l l   2 . 0   发 布 的 时 候 ， 我 们 意 识 到 是 时 候 使 用 静 态 网 站 了 ！ 特 别 是   C o l l e c t i o n s 文 档 类 型 这 个 新 特 性 使 得 定 义 自 己 的 文 件 结 构 成 为 可 能 。 不 仅 如 此 ， J e k y l l   2 . 0   还 增 加 了   S a s s   和   C o f f e e S c r i p t   的 支 持 ， 让 前 端 代 码 的 编 写 更 简 单 。 开 源 的 好 处 在 于 它 是 开 放 的 。 我 们 迁 移 到   J e k y l l   后 ， 我 们 也 向   J e k y l l 项 目 发 起 了 很 多 p u l l   r e q u e s t s ， 贡 献 代 码 ， 使 得 它 能 更 好 的 服 务   G i t h u b P a g e s   的 广 大 用 户 。 这 时 ， 我 们 的 工 作 流 程 发 生 了 小 小 的 变 化 。 但 我 们 仍 然 使 用   M a r k d o w n   ， 将 写 好 的 内 容 提 交 到 仓 库 供 他 人 审 校 。 当 我 们 的 提 交 被 合 并 之 后 ， G i t h u b   P a g e s   网 站 将 会 在 几 秒 内 自 动 快 速 创 建 并 部 署 。 下 面 是 我 们 就 如 何 使 用   J e k y l l   的 核 心 功 能 以 及 对   G i t h u b   帮 助 系 统 起 增 强 效 果 的 插 件 列 了 一 个 简 单 的 纲 要 。
我 们 的 法 宝 我 们 主 要 依 靠   J e k y l l   核 心 代 码 的 功 能 来 完 成 任 务 ， 这 样 更 省 心 省 力 ， 而 不 是 将 大 量 精 力 用 于 维 护 自 定 义 插 件 。 J e k y l l   2 . 0   提 供 的 全 新 插 件   C o n v e r t e r   可 以 将 任 何 标 记 自 动 转 换 成   H T M L 。 这 样 用 户 写 文 章 就 可 以 无 拘 无 束 ， J e k y l l   只 负 责 运 行 最 后 生 成 的 H T M L 文 件 就 好 了 。 比 如 ， 你 可 以 使 用   A s c i i D o c   语 法 发 贴 子 。 最 后 ， 我 们 开 发 了   j e k y l l - h t m l - p i p e l i n e   插 件 ， 是 我 们 之 前 开 源 的   h t m l - p i p e l i n e   在   J e k y l l   上 的 增 强 版 。 这 个 确 保 了 我 们 的 帮 助 站 点 的 内 容 在 整 个 G i t h u b   上 没 有 任 何 差 异 。 同 时 我 们 也 用 自 己 开 发 的   M a r k d o w n   f i l t e r   插 件 提 供 一 些 语 法 扩 展 ， 进 一 步 降 低 了 文 档 编 写 的 难 度 。 搜 索 在 之 前 的 R a i l s 站 点 上 ， 我 们 使 用 了 E l a s t i c S e a r c h   提 供 商 索 引 我 们 的 数 据 库 并 为 我 们 的 帮 助 站 点 实 现 了 搜 索 系 统 。 现 在 ， 我 们 使 用 l u n r - j s 来 提 供 更 加 快 速 的 客 户 端 搜 索 体 验 。 通 过 我 们 的 分 析 筛 选 ， 我 们 发 现 绝 大 多 数 的 用 户 依 赖 于 外 部 搜 索 服 务 提 供 商 来 获 得 我 们 的 文 档 。 在 迁 移 期 间 或 者 迁 移 后 ， 将 大 量 的 精 力 花 在 服 务 器 端 的 搜 索 解 决 方 案 是 没 有 什 么 意 义 的 。 阅 读 原 文
回复

举报

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

使用Markdown编辑器编辑 使用富文本编辑器编辑

Archiver| 手机版| 小黑屋|
Powered by Discuz! X3.4 Copyright © 2001-2020, Tencent Cloud. 商业源码建议获取授权，如侵犯您的权益，请联系客服处理