贡献 Ceph 文档

帮助 Ceph 项目最简单的方法就是贡献文档。随着 Ceph 用户量的增长和开发的迅速推进,越来越多的人在更新文档、增加新条目。即使是修正拼写错误或澄清说明这样的小贡献也会有助于提升 Ceph 项目的品质。

Ceph 文档源码位于 Ceph 源码库的 ceph/doc 目录下,由 Python Sphinx 渲染成 HTML 和手册页。 http://ceph.com/docs 链接默认展示 master 分支,也可以查看较早分支(如 argonaut )或者未来分支(如 next )的文档,以及正在改进的分支,只需把 master 改成你想看的分支即可。

如何贡献

贡献文档和贡献源码的过程基本相同,唯一不同的就是你编译的是文档源码而不是程序源码。大致步骤如下:

  1. 获取源代码
  2. 选择分支
  3. 开始更改
  4. 构建文档源码
  5. 提交变更
  6. 推送变更
  7. 发出 Pull 请求
  8. 通知相关人员

获取源代码

Ceph 文档位于和 Ceph 源码同一仓库内的 ceph/doc 目录下,关于 github 和 Ceph 的详细情况见加入 Ceph 社区!

最常用的贡献方法是分支并拉入。为此,必须先做到:

  1. 在本地安装 git 。在 Debian/Ubuntu 下执行:

    sudo apt-get install git

    在 Fedora 下执行:

    sudo yum install git

    在 CentOS/RHEL 下执行:

    sudo yum install git
  2. .gitconfig 配置文件里配置自己的名字和邮件地址。

    [user]
       email = {your-email-address}
       name = {your-name}

    例如:

    git config --global user.name "John Doe"
    git config --global user.email johndoe@example.com
  3. 创建 github 帐户(假如没有的话)。

  4. 创建 Ceph 项目的分支,参见 https://github.com/ceph/ceph

  5. 把你的分支项目克隆到本机。

Ceph 文档按主要组件来分类组织。

  • Ceph 存储集群:Ceph 存储集群文档位于 doc/rados 目录下。
  • Ceph 块设备:Ceph 块设备文档位于 doc/rbd 目录下。
  • Ceph 对象存储:Ceph 对象存储文档位于 doc/radosgw 目录下。
  • Ceph 文件系统:Ceph 文件系统文档位于 doc/cephfs 目录下。
  • 安装(快速):快速入门文档位于 doc/start 目录下。
  • 安装(手动):手动安装文档位于 doc/install 目录下。
  • 手册页:手册源码位于 doc/man 目录下;
  • 开发者:开发者文档位于 doc/dev 目录下;
  • 图片:如果你想上传图片,如 JPEG 或 PNG 文件,应该放到 doc/images 目录下。

选择分支

如果只是细小的变更,像修正排版错误、或澄清措辞,直接提交到 master 分支即可。为当前版本的功能提供文档时也应该提交到 master 分支。 master 是最常用的分支。

git checkout master

对未来版本的文档作出修改时应该提交到 next 分支, next 分支是第二常用的分支。

git checkout next

当你在为尚未发布的功能写文档时,如果这部分文档和已追踪的某个问题有关,或者想在它被合并到 master 分支前看看它在 ceph.com 网站上的预览效果,你应该新建一个分支。为标识这是个只包含文档的更新,按惯例用 wip-doc 作前缀,采用 wip-doc-{your-branch-name} 的格式。如果此分支和 http://tracker.ceph.com/issues 里的某个问题相关,分支名最好包含问题编号,例如,如果某文档分支是为 #4000 这个问题写的,按惯例这个分支名就是 wip-doc-4000 ,对应的问题追踪 URL 就是 http://tracker.ceph.com/issues/4000

Note

请不要把文档贡献和源码贡献混在同一个 pull 请求里。因为文档由编辑审阅,而源码由工程师审阅。您分别提交文档和源码贡献时,会加快合并进度,我们也不用让您重新分开提交。

创建分支前,确保本地和远程仓库都不存在同名分支。

git branch -a | grep wip-doc-{your-branch-name}

如果确实不存在,就可以创建了:

git checkout -b wip-doc-{your-branch-name}

开始更改

修改文档很简单,打开 restructuredText 文件、修改、保存即可。相关的语法请参考 文档风格指南

新增文档要在 doc 目录或其子目录下新建 restructuredText 文件,并以 *.rst 作后缀。还必须包含对它的引用:如超链接或目录条目。某个顶极目录中的 index.rst 文件通常包含一个 TOC ,你可以在这里添加新文件名。所有文档都必须有标题,详情见标题

你新建的文档不会自动被 git 跟踪。如果想把它加进仓库,必须用 git add {path-to-filename} 命令。比如,在 Ceph 仓库的顶极目录下,把 example.rst 文件加到 rados 子目录下,可以这样:

git add doc/rados/example.rst

要删除某个文档,应该用 git rm {path-to-filename} ,比如:

git rm doc/rados/example.rst

还必须从其他文档删除与之相关的引用。

构建文档源码

要想构建文档,先进入 ceph 仓库目录:

cd ceph

在 Debian/Ubuntu 上执行此命令构建文档:

admin/build-doc

在 Fedora 上执行:

admin/build-doc

在 CentOS/RHEL 上执行:

admin/build-doc

执行 admin/build-doc 后会在 ceph 下创建一个 build-doc 目录。你也许还得在 ceph/build-doc 下新建一个目录用于存放 Javadoc 的输出。

mkdir -p output/html/api/libcephfs-java/javadoc

构建脚本 build-doc 可能会输出警告和报错。在提交更改之前,必须修复文档中的错误,应该尽量消除和语法相关的警告。

Important

你必须核实所有超链接,损坏的超链接会中止构建过程。

文档构建完成后你就可以到源码目录下查看了:

cd build-doc/output

那里应该有 html 目录和 man 目录分别存放着 HTML 和手册页格式的文档。

构建源码(首次)

Ceph 用 Python Sphinx 构建文档,此软件一般都没安装。首次构建文档时,它会生成一个用于 doxygen 的 XML 树,这个过程比较耗时.

Python Sphinx 的依赖软件包根据发行版不同而有所区别。首次构建文档时,如果你没安装这些依赖包,构建脚本会提示你。要运行 Sphinx 并成功构建文档,至少要安装下面这些软件包:

Debian/Ubuntu

  • gcc
  • python-dev
  • python-pip
  • python-virtualenv
  • python-sphinx
  • libxml2-dev
  • libxslt1-dev
  • doxygen
  • graphviz
  • ant
  • ditaa

Fedora

  • gcc
  • python-devel
  • python-pip
  • python-virtualenv
  • python-docutils
  • python-jinja2
  • python-pygments
  • python-sphinx
  • libxml2-devel
  • libxslt1-devel
  • doxygen
  • graphviz
  • ant
  • ditaa

CentOS/RHEL

  • gcc
  • python-devel
  • python-pip
  • python-virtualenv
  • python-docutils
  • python-jinja2
  • python-pygments
  • python-sphinx
  • libxml2-dev
  • libxslt1-dev
  • doxygen
  • graphviz
  • ant

安装每一个缺少的依赖,基于 Debian/Ubuntu 发行版的系统可以用此命令安装:

sudo apt-get install gcc python-dev python-pip python-virtualenv libxml2-dev libxslt-dev doxygen graphviz ant ditaa
sudo apt-get install python-sphinx

在 Fedora 发行版上可以执行:

sudo yum install gcc python-devel python-pip python-virtualenv libxml2-devel libxslt-devel doxygen graphviz ant
sudo pip install html2text
sudo yum install python-jinja2 python-pygments python-docutils python-sphinx
sudo yum install jericho-html ditaa

在 CentOS/RHEL 发行版上,最好安装 epel ( Extra Packages for Enterprise Linux )软件库,因为它提供了很多默认软件库所没有的软件包。可执行此命令安装 epel

wget http://ftp.riken.jp/Linux/fedora/epel/7/x86_64/e/epel-release-7-2.noarch.rpm
sudo yum install epel-release-7-2.noarch.rpm

在 CentOS/RHEL 发行版上可以执行:

sudo yum install gcc python-devel python-pip python-virtualenv libxml2-devel libxslt-devel doxygen graphviz ant
sudo pip install html2text

对于 CentOS/RHEL 发行版,其余软件包不包含在默认及 epel 软件仓库内,所以得到 http://rpmfind.net/ 找,然后去合适的镜像下载并安装它们,比如:

wget ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/python-jinja2-2.7.2-2.el7.noarch.rpm
sudo yum install python-jinja2-2.7.2-2.el7.noarch.rpm
wget ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm
sudo yum install python-pygments-1.4-9.el7.noarch.rpm
wget ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm
sudo yum install python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm
wget ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/python-sphinx-1.1.3-8.el7.noarch.rpm
sudo yum install python-sphinx-1.1.3-8.el7.noarch.rpm

Ceph 文档大量使用了 ditaa ,它没有对应的 CentOS/RHEL7 二进制包。如果你要修改 ditaa 图,那你必须安装 ditaa 才能确认你新增或修改的 ditaa 图可以正确渲染。你可以自己去找与 CentOS/RHEL7 发行版兼容的包,并手动安装。在 CentOS/RHEL7 下 ditaa 依赖下列软件包:

  • jericho-html
  • jai-imageio-core
  • batik

http://rpmfind.net/ 找兼容的 ditaa 及其依赖,然后从某个镜像下载并安装它们。例如:

wget ftp://rpmfind.net/linux/fedora/linux/releases/20/Everything/x86_64/os/Packages/j/jericho-html-3.2-6.fc20.noarch.rpm
sudo yum install jericho-html-3.2-6.fc20.noarch.rpm
wget ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm
sudo yum install jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm
wget ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/batik-1.8-0.12.svn1230816.el7.noarch.rpm
sudo yum install batik-1.8-0.12.svn1230816.el7.noarch.rpm
wget ftp://rpmfind.net/linux/fedora/linux/releases/20/Everything/x86_64/os/Packages/d/ditaa-0.9-10.r74.fc20.noarch.rpm
sudo yum install ditaa-0.9-10.r74.fc20.noarch.rpm

Important

不要安装 fc21 版本的 ditaa rpm包,因为它使用的 JRE 比 CentOS/RHEL7 自带的新,这样会导致冲突并抛出异常 Exception ,程序也因此不能运行。

安装好所有这些包之后,就可以按照构建文档源码里的步骤构建文档了。

提交变更

Ceph文档的提交虽然简单,却遵循着严格的惯例:

  • 一次提交应该只涉及一个文件(方便回退),也可以一次提交有关联的多个文件。不相干的变更不应该放到同一提交内。
  • 每个提交都必须有注释。
  • 提交的注释必须doc: 打头(应严格遵守)。
  • 注释摘要必须只有一行(应严格遵守)。
  • 额外的注释可以写到摘要下面空一行的地方,但应该简单明了。
  • 提交可以包含 Fixes: #{bug number} 字样。
  • 提交必须包含 Signed-off-by: Firstname Lasname <email> (应严格遵守)。

Tip

请遵守前述惯例,特别是标明了 (应严格遵守) 的那些,否则你的提交会被打回,修正后才能重新提交。

下面是个通用提交的注释(首选):

doc: Fixes a spelling error and a broken hyperlink.

Signed-off-by: John Doe <john.doe@gmail.com>

下面的注释里有包含 BUG 的引用。

doc: Fixes a spelling error and a broken hyperlink.

Fixes: #1234

Signed-off-by: John Doe <john.doe@gmail.com>

下面的注释包含一句概要和详述,在摘要和详述之间用空行隔开了:

doc: Added mon setting to monitor config reference

Describes 'mon setting', which is a new setting added
to config_opts.h.

Signed-off-by: John Doe <john.doe@gmail.com>

执行下列命令提交变更:

git commit -a

管理文档提交的一个比较简单的方法是用 git 的图形化前端,如 gitk 提供了可查看仓库历史的图形界面; git-gui 提供的图形界面可查看未提交的变更、把未提交变更暂存起来、提交变更、并推送到自己的 Ceph 分支仓库。

在 Debian/Ubuntu 上执行以下命令安装:

sudo apt-get install gitk git-gui

在 Fedora/CentOS/RHEL 上执行以下命令安装:

sudo yum install gitk git-gui

然后执行

cd {git-ceph-repo-path}
gitk

最后,点击 File->Start git gui 打开图形界面。

推送变更

你完成一或多个提交后,必须从本地推送到位于 github 的仓库。某些图形化工具(如 git-gui )有推送菜单。如果你之前创建了分支:

git push origin wip-doc-{your-branch-name}

否则:

git push

发出 Pull 请求

前面已经说过了,你可以依照分支并拉入方法贡献文档。

通知相关人员

发出 Pull 请求后,还需通知相关人员。通常,文档的接收请求应该发给 John Wilkins

文档风格指南

Ceph 文档项目的目标之一就是文档的可读性,包括原始的 restructuredText 和渲染后的 HTML 页面。进入 Ceph 源码库,随便找个文档查看其源码,你会发现它在终端下就像已经渲染过的 HTML 页面一样清晰明了。另外,也许你还看到 ditaa 格式的图表渲染的也很漂亮。

cat doc/architecture.rst | less

为了维持一致性,请遵守下面的风格指南。

标题

  1. 文档标题: 标题行的前/后各加一行 = ,且标题行首、行尾各有一个空格,详情见文档标题
  2. 章节标题: 章节标题行下是一行 = ,且行首、行尾都没有空格。章节标题前应该有两个空行(除非前面是内嵌引用)。详情见章节
  3. 小节标题: 小节标题行下是一行 - ,且行首、行尾都没有空格。小节标题前应该有两个空行(除非前面是内嵌引用)。

正文

通常,我们把正文限制在 80 列之内,这样它在任何标准终端内都可以正确显示,行首、行尾都不能有空格。我们应该尽可能维持此惯例,包括文本、项目、引文文本(允许例外)、表格、和 ditaa 图形。

  1. 段落: 段落前后各有一空行,且宽度不超过 80 字符,这样文档源码就可以在任何标准终端正确显示。

  2. 引文文本: 要创建引文文本(如展示命令行用法),前一段应以 :: 结尾,或者先加一个空行、然后在新行上输入 :: 、之后再加一个空行。之后以 TAB (首选)或 3 个空格缩进,开始输入引文。

  3. 缩进文本: 像要点这样的缩进文本(如: - some text )可能会延伸很多行,后续行应该延续和首行缩进(数字、圆点等)相同的起始列。

    缩进文本也可以包含引文。这时,缩进文本应该用空格标记、引文用 TAB 标记。按照这个惯例,你就可以额外增加缩进段落,并在其中嵌入引文示例(引文段前加空行,行前用空格缩进)。

  4. 编号列表: 需编号的列表应该在行首用 # 标识以实现自动编号,而不是手动标识,这样在条目顺序变更时就不用重新编号了。

  5. 代码示例: Ceph 文档中可以用 .. code-block::<language> 按语种对源码进行高亮显示,这是对源码的首选标记方法。然而,如果在编号列表中使用这个标签,将导致从 1 开始重新编号。详情见显示代码示例

段落分级标记

Ceph 文档项目用段落分级标记来高亮显示要点。

  1. Tip 提示:.. tip:: 指令标识额外信息,以助读者或操作员脱困。
  2. Note 注:.. note:: 指令来高亮显示一个要点。
  3. Important 重要:.. important:: 指令来高亮显示重要要求或警告(如可能导致数据丢失的事情)。尽量少用,因为它会渲染成红色背景。
  4. Version Added 版本新增:..versionadded:: 指令来标识新增功能或配置选项,这样用户才能知道此选项适用的最低版本。
  5. Version Changed 版本变更:.. versionchanged:: 指令标识用法或配置选项的变更。
  6. Deprecated 已过时:.. deprecated:: 指令标识不再推荐或将被移除的 CLI 用法、功能、或配置选项。
  7. Topic 论题:.. topic:: 指令来封装位于文档主体之外的文本。详情见 topic 指令

TOC 和超链接

所有文档都必须被链接到其他文档或列表内,否则构建文档时会被警告。

Ceph 项目采用 .. toctree:: 指令(详情见 TOC 树)。渲染时,最好用 :maxdepth: 参数把 TOC 修饰得简洁些。

链接目标是个惟一标识符(如 .. _unique-target-id: )、而且某一引用明确引用了它(如 :ref: `uniq-target-id` ),这时应该优先用 :ref: 语法。这样,如果源文件位置或文档结构变更之后链接仍然有效,详情见交叉引用任意位置

Ceph 文档内的链接可以这样写:反引号(重音符号)、之后跟着链接文本、另一个反引号、最后是下划线; Sphinx 允许你内联链接目标。然而,我们喜欢这样用:在文档底部加 .. _Link Text: ../path ,因为这样的写法在命令行下可读性好。