注意

本文档适用于 Ceph 的开发版本。

文档化 Ceph

您可以通过为文档做出贡献来帮助 Ceph 项目。即使是很小的贡献也能帮助 Ceph 项目。

建议文档更正的最简单方法是发送电子邮件至 ceph-users@ceph.io。在主题行中包含字符串“ATTN: DOCS”或“Attention: Docs”或“Attention: Documentation”。在电子邮件正文中，包含需要更正的文本（以便我能在仓库中找到它）以及您的更正。

建议文档更正的另一种方法是创建拉取请求。有关针对 Ceph 文档创建拉取请求的说明，请参阅做出贡献部分。

如果这是您第一次改进文档，或者如果您发现了小错误（例如拼写错误或打字错误），发送电子邮件会比创建拉取请求更容易。除非您指示 Ceph Upstream Documentation 不要为您署名，否则您将因所做的改进而获得致谢。

文档在仓库中的位置

Ceph 文档源位于 Ceph 仓库的 ceph/doc 目录中。Python Sphinx 将源渲染为 HTML 和 manpage。

查看旧版 Ceph 文档

https://docs.ceph.net.cn 链接默认显示最新版本的文档（例如，如果“Reef”是最新版本，则默认情况下 https://docs.ceph.net.cn 显示 Reef 的文档），但您可以通过替换 URL 中的版本名称来查看 Ceph 旧版本的文档（例如，将 https://docs.ceph.net.cn/en/latest/ 中的 reef 替换为您首选的分支名称，例如 quincy，以创建读取 https://docs.ceph.net.cn/en/latest/ 的 URL）。

做出贡献

做出文档贡献涉及与做出代码贡献相同的基本过程，但有一个例外：您必须构建文档源而不是编译程序源。此序列（构建文档源的序列）包括以下步骤

获取源代码
选择分支
做出更改
构建源代码
提交更改
推送更改
创建拉取请求
通知我们

获取源代码

Ceph 文档的源是 Ceph 仓库中 ceph/doc 目录中的 ReStructured Text 文件集合。有关 GitHub 和 Ceph 的详细信息，请参阅参与 Ceph 社区！。

使用 Fork and Pull 方法做出文档贡献。为此，您必须

在本地安装 git。在 Debian 或 Ubuntu 中，运行以下命令
```
sudo apt-get install git
```
在 Fedora 中，运行以下命令
```
sudo yum install git
```
在 CentOS/RHEL 中，运行以下命令
```
sudo yum install git
```

确保您的 .gitconfig 文件已配置为包含您的姓名和电子邮件地址

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

例如

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

创建一个 github 帐户（如果您没有）。
Fork Ceph 项目。请参阅 https://github.com/ceph/ceph。
将您的 Ceph 项目分支克隆到您的本地主机。这创建了所谓的“本地工作副本”。

Ceph 文档按组件组织

Ceph Storage Cluster: Ceph Storage Cluster 文档位于 doc/rados 目录中。
Ceph Block Device: Ceph Block Device 文档位于 doc/rbd 目录中。
Ceph Object Storage: Ceph Object Storage 文档位于 doc/radosgw 目录中。
Ceph File System: Ceph File System 文档位于 doc/cephfs 目录中。
安装（快速）： 快速入门文档位于 doc/start 目录中。
安装（手动）： 有关 Ceph 手动安装的文档位于 doc/install 目录中。
Manpage： Manpage 源位于 doc/man 目录中。
开发人员： 开发人员文档位于 doc/dev 目录中。
图片： 包括 JPEG 和 PNG 文件在内的图片存储在 doc/images 目录中。

选择分支

当您对文档进行小幅更改时，例如修复印刷错误或澄清解释，请使用 main 分支（默认）。在为当前版本中的功能做出贡献时，您也应该使用 main 分支。main 是最常用的分支。

git checkout main

当您对影响即将发布的版本的文档进行更改时，请使用 next 分支。next 是第二常用的分支。

git checkout next

当您做出重大贡献时，例如当前版本中尚未包含的新功能；如果您的贡献与具有跟踪器 ID 的问题相关；或者，如果您希望在合并到 main 分支之前在 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。

注意

请不要将文档贡献和源代码贡献混入单个提交中。当您将文档提交与源代码提交分开时，可以简化审阅过程。我们强烈建议任何添加功能或配置选项的拉取请求也应包含描述更改的文档提交。

在创建分支名称之前，请确保它在本地或远程仓库中尚不存在。

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}。例如，从仓库的顶层目录中，将 example.rst 文件添加到 rados 子目录中如下所示

git add doc/rados/example.rst

删除文档涉及使用 git rm {path-to-filename} 将其从仓库中删除。例如

git rm doc/rados/example.rst

您还必须从其他文档中删除对已删除文档的任何引用。

构建源代码

要构建文档，请导航到 ceph 仓库目录

cd ceph

注意

包含 build-doc 和 serve-doc 的目录必须包含在 PATH 环境变量中，这些命令才能起作用。

要在 Debian/Ubuntu、Fedora 或 CentOS/RHEL 上构建文档，请执行

admin/build-doc

要扫描外部链接的可达性，请执行

admin/build-doc linkcheck

运行 admin/build-doc 会在 ceph 下创建一个 build-doc 目录。您可能需要在 ceph/build-doc 下创建一个目录用于 Javadoc 文件输出

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

构建脚本 build-doc 产生的输出部分由错误和警告组成。您必须在提交更改之前修复您修改的文档中的错误，并且您应该修复与您修改的语法相关的警告。

重要

您必须验证所有超链接。如果超链接损坏，它会自动破坏构建！

构建文档集后，您可以通过运行以下命令在 https://:8080/ 启动 HTTP 服务器以查看它

admin/serve-doc

您也可以导航到 build-doc/output 来检查已构建的文档。在 build-doc/output 中有一个 html 目录和一个 man 目录，分别包含 HTML 和 manpage 格式的文档。

构建源代码（首次）

Ceph 使用 Python Sphinx，它与发行版无关。第一次构建 Ceph 文档时，会生成 doxygen XML 树。这可能会很耗时。

Python Sphinx 的某些依赖项因发行版而异。第一次构建文档时，构建脚本会通知您未安装的依赖项。

要成功运行 Sphinx 并构建文档，需要以下软件包

Debian/Ubuntu

gcc
python3-dev
python3-pip
python3-sphinx
python3-venv
libxml2-dev
libxslt1-dev
doxygen
graphviz
ant
ditaa
cython3

Fedora

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

CentOS/RHEL

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

安装主机上未安装的每个依赖项。对于 Debian/Ubuntu 发行版，运行以下命令

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

对于 Fedora 发行版，运行以下命令

sudo yum install gcc python-devel python-pip 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，请运行以下命令

sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

对于 CentOS/RHEL 发行版，运行以下命令

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

对于 CentOS/RHEL 发行版，剩余的 Python 软件包在默认仓库或 epel 仓库中不可用。使用 http://rpmfind.net/ 查找软件包。然后从镜像下载并安装它们。例如

wget http://rpmfind.net/linux/centos/7/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 http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm
sudo yum install python-pygments-1.4-9.el7.noarch.rpm
wget http://rpmfind.net/linux/centos/7/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 http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-sphinx-1.1.3-11.el7.noarch.rpm
sudo yum install python-sphinx-1.1.3-11.el7.noarch.rpm

Ceph 文档广泛使用 ditaa，它不是为 CentOS/RHEL 构建的。如果您更改 ditaa 图表，则必须安装 ditaa 以在提交更改之前验证它们是否正确渲染。您可以检索适用于 CentOS/RHEL 发行版的兼容所需软件包并手动安装它们。要在 CentOS/RHEL 上运行 ditaa，需要以下依赖项

jericho-html
jai-imageio-core
batik

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

wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/j/jericho-html-3.3-4.fc22.noarch.rpm
sudo yum install jericho-html-3.3-4.fc22.noarch.rpm
wget http://rpmfind.net/linux/centos/7/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 http://rpmfind.net/linux/centos/7/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 http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/d/ditaa-0.9-13.r74.fc21.noarch.rpm
sudo yum install ditaa-0.9-13.r74.fc21.noarch.rpm

安装这些软件包后，请按照构建源代码中的步骤构建文档。

提交更改

Ceph 文档提交很简单，但遵循严格的约定

一个提交应该（SHOULD）每个提交有 1 个文件（这简化了回滚）。您可以（MAY）提交具有相关更改的多个文件。不相关的更改不应该（SHOULD NOT）放在同一个提交中。
一个提交必须（MUST）有一个注释。
提交注释必须（MUST）以 doc: 开头。（严格）
注释摘要必须（MUST）只有一行。（严格）
附加注释可以在摘要后的空白行之后跟随，但应该简洁。
提交可以（MAY）包括 Fixes: https://tracker.ceph.com/issues/{bug number}。
提交必须（MUST）包括 Signed-off-by: Firstname Lastname <email>。（严格）

提示

请特别遵循上述约定中标记为 (strict) 的部分，否则您将被要求修改您的提交以符合此约定。

以下是常见的提交注释（首选）

doc: Fixes a spelling error and a broken hyperlink.

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

以下注释包含对错误的引用。

doc: Fixes a spelling error and a broken hyperlink.

Fixes: https://tracker.ceph.com/issues/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 提供了一个用于查看未提交更改、暂存更改以进行提交、提交更改并将其推送到您的 fork 的 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

创建拉取请求

如前所述，您可以使用 Fork and Pull 方法做出文档贡献。

合并多余的提交

每个拉取请求应该只与单个提交相关联。如果您对正在使用的功能分支进行了多次提交，则需要“合并”多个提交。“合并”（squashing）是特定类型“交互式 rebase”的俗称。合并可以通过多种方式完成，但这里的示例将处理存在三个提交且保留所有三个提交中的更改的情况。这三个提交将被合并为一个提交。

进行稍后将合并的提交。

进行第一次提交。

doc/glossary: improve "CephX" entry

Improve the glossary entry for "CephX".

Signed-off-by: Zac Dover <zac.dover@proton.me>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch wip-doc-2023-03-28-glossary-cephx
# Changes to be committed:
#       modified:   glossary.rst
#

进行第二次提交。

doc/glossary: add link to architecture doc

Add a link to a section in the architecture document, which link
will be used in the process of improving the "CephX" glossary entry.

Signed-off-by: Zac Dover <zac.dover@proton.me>

   # Please enter the commit message for your changes. Lines starting
   # with '#' will be ignored, and an empty message aborts the commit.
   #
   # On branch wip-doc-2023-03-28-glossary-cephx
   # Your branch is up to date with 'origin/wip-doc-2023-03-28-glossary-cephx'.
   #
   # Changes to be committed:
   #       modified:   architecture.rst

进行第三次提交。

doc/glossary: link to Arch doc in "CephX" glossary

Link to the Architecture document from the "CephX" entry in the
Glossary.

Signed-off-by: Zac Dover <zac.dover@proton.me>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch wip-doc-2023-03-28-glossary-cephx
# Your branch is up to date with 'origin/wip-doc-2023-03-28-glossary-cephx'.
#
# Changes to be committed:
#       modified:   glossary.rst

现在功能分支中有三个提交。我们现在将开始将它们合并为一个提交的过程。

运行命令 git rebase -i main，它将当前分支（功能分支）与 main 分支进行 rebase
```
git rebase -i main
```

现在显示已对功能分支进行的提交列表，如下所示

pick d395e500883 doc/glossary: improve "CephX" entry
pick b34986e2922 doc/glossary: add link to architecture doc
pick 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary

# Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
#         create a merge commit using the original merge commit's
#         message (or the oneline, if no original merge commit was
#         specified); use -c <commit> to reword the commit message
# u, update-ref <ref> = track a placeholder for the <ref> to be updated
#                       to this position in the new commits. The <ref> is
#                       updated at the end of the rebase
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.

找到屏幕上显示“pick”的部分。这是您将更改的部分。目前有三个标记为“pick”的提交。我们将选择其中一个保持标记为“pick”，并将另外两个提交标记为“squash”。

将三个提交中的两个标记为 squash

pick d395e500883 doc/glossary: improve "CephX" entry
squash b34986e2922 doc/glossary: add link to architecture doc
squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary

# Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
#         create a merge commit using the original merge commit's
#         message (or the oneline, if no original merge commit was
#         specified); use -c <commit> to reword the commit message
# u, update-ref <ref> = track a placeholder for the <ref> to be updated
#                       to this position in the new commits. The <ref> is
#                       updated at the end of the rebase
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.

现在我们创建一个适用于所有已合并在一起的提交的提交消息

当您保存并关闭您指定要合并的提交列表时，所有三个提交消息的列表出现，如下所示

# This is a combination of 3 commits.
# This is the 1st commit message:

doc/glossary: improve "CephX" entry

Improve the glossary entry for "CephX".

Signed-off-by: Zac Dover <zac.dover@proton.me>

# This is the commit message #2:

doc/glossary: add link to architecture doc

Add a link to a section in the architecture document, which link
will be used in the process of improving the "CephX" glossary entry.

Signed-off-by: Zac Dover <zac.dover@proton.me>

# This is the commit message #3:

doc/glossary: link to Arch doc in "CephX" glossary

Link to the Architecture document from the "CephX" entry in the
Glossary.

Signed-off-by: Zac Dover <zac.dover@proton.me>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date:      Tue Mar 28 18:42:11 2023 +1000
#
# interactive rebase in progress; onto 0793495b9d1
# Last commands done (3 commands done):
#    squash b34986e2922 doc/glossary: add link to architecture doc
#    squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary
# No commands remaining.
# You are currently rebasing branch 'wip-doc-2023-03-28-glossary-cephx' on '0793495b9d1'.
#
# Changes to be committed:
#       modified:   doc/architecture.rst
#       modified:   doc/glossary.rst

提交消息已修改为此处呈现的更简单形式

doc/glossary: improve "CephX" entry

Improve the glossary entry for "CephX".

Signed-off-by: Zac Dover <zac.dover@proton.me>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date:      Tue Mar 28 18:42:11 2023 +1000
#
# interactive rebase in progress; onto 0793495b9d1
# Last commands done (3 commands done):
#    squash b34986e2922 doc/glossary: add link to architecture doc
#    squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary
# No commands remaining.
# You are currently rebasing branch 'wip-doc-2023-03-28-glossary-cephx' on '0793495b9d1'.
#
# Changes to be committed:
#       modified:   doc/architecture.rst
#       modified:   doc/glossary.rst

将合并后的提交从您的本地工作副本强制推送到远程上游分支。强制推送是必要的，因为新合并的提交在远程中没有祖先。如果这让您感到困惑，只需运行此命令即可，无需过多思考

git push -f

Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 8 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 722 bytes | 722.00 KiB/s, done.
Total 5 (delta 4), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
To github.com:zdover23/ceph.git
 + b34986e2922...02e3a5cb763 wip-doc-2023-03-28-glossary-cephx -> wip-doc-2023-03-28-glossary-cephx (forced update)

通知我们

如果过了一段时间，您提出的拉取请求尚未得到审核，请联系组件负责人，询问为什么需要这么长时间。有关组件负责人的列表，请参阅组件团队负责人。

文档风格指南

Ceph 文档项目的一个目标是确保文档在原生 reStructuredText 格式及其渲染格式（如 HTML）中的可读性。导航到您的 Ceph 仓库并以其原生格式查看文档。您可能会注意到它在终端中通常与在其渲染的 HTML 格式中一样清晰。此外，您可能还会注意到 ditaa 格式的图表在文本模式下也能合理渲染。

less doc/architecture.rst

查看以下风格指南以保持这种一致性。

标题

文档标题： 文档标题使用 = 字符作为上划线和下划线，标题文本行有一个前导空格和一个尾随空格。有关详细信息，请参阅文档标题。
章节标题： 章节标题使用 = 字符作为下划线，文本没有前导空格或尾随空格。章节标题前应有两个回车符（除非其前面有内联引用）。有关详细信息，请参阅章节。
小节标题： 小节标题使用 _ 字符作为下划线，文本没有前导空格或尾随空格。小节标题前应有两个回车符（除非其前面有内联引用）。

正文

作为一般规则，我们希望文本在第 80 列换行，以便它在命令行界面中可读，没有前导或尾随空格。在可能的情况下，我们希望在文本、列表、文字文本（允许例外）、表格和 ditaa 图形中保持此约定。

段落: 段落有一个前导回车和一个尾随回车，并且应该少于或等于 80 个字符宽，以便文档可以在命令行终端中以原生格式阅读。
文字文本： 要创建文字文本示例（例如，命令行用法），请使用 :: 终止前面的段落或输入一个回车符在前面的段落之后创建一个空行；然后，在单独的行上输入 ::，后面跟着另一个空行。然后，文字文本以制表符缩进（首选）或 3 个字符的空格缩进开始。
缩进文本： 缩进文本（例如项目符号点，例如 - some text）可以跨多行。后续行的文本应从与缩进文本文本相同的字符位置开始（减去数字、项目符号等）。

缩进文本可能包含文字文本示例。虽然文本缩进应该用空格完成，但文字文本示例应该用制表符缩进。此约定使您能够通过留一个空行并以空格缩进开始后续段落，在文字示例之后添加另一个缩进段落。
编号列表： 编号列表应该使用自动编号，通过以 #. 而不是实际数字开始编号缩进，这样可以重新定位编号段落而无需手动重新编号。
代码示例： Ceph 支持使用 .. code-block::<language> 角色，以便您可以向源示例添加高亮显示。这对于源代码是首选。但是，如果此标签用作编号列表中的示例，它将导致自动编号从 1 重新开始。有关详细信息，请参阅显示代码示例。

段落级标记

Ceph 项目使用段落级标记来突出显示要点。

提示： 使用 .. tip:: 指令提供有助于读者或引导读者远离麻烦的附加信息。
注意: 使用 .. note:: 指令突出显示重要点。
重要： 使用 .. important:: 指令突出显示重要的要求或注意事项（例如，任何可能导致数据丢失的内容）。谨慎使用此指令，因为它会以红色渲染。
版本新增： 使用 .. versionadded:: 指令用于新功能或配置设置，以便用户知道使用功能的最低版本。
版本更改： 使用 .. versionchanged:: 指令用于用法或配置设置的更改。
已弃用： 当 CLI 用法、功能或配置设置不再首选或将停止使用时，使用 .. deprecated:: 指令。
主题： 使用 .. topic:: 指令封装文档主要流程之外的文本。有关其他详细信息，请参阅 topic directive。

目录 (TOC) 和超链接

Ceph 文档套件中的文档遵循本节中解释的某些约定。

Sphinx 控制的 Ceph 文档套件中的每个文档（每个 .rst 文件）都必须链接到 (1) 文档套件中的另一个文档或 (2) 目录 (TOC)。如果文档套件中的任何文档未以这种方式链接，则 build-doc 脚本在尝试构建文档时会生成警告。

Ceph 项目使用 .. toctree:: 指令。有关详细信息，请参阅 TOC 树。渲染目录 (TOC) 时，请指定 :maxdepth: 参数，以便渲染的 TOC 不会太长。

使用 :ref: 语法，其中链接目标包含特定的唯一标识符（例如，.. _unique-target-id:）。指向由 .. _unique-target-id: 指定的章节的链接如下所示：:ref:`unique-target-id`。如果遵循此约定，则即使源文件在 ceph/doc 目录中移动，.rst 源文件中的链接也将起作用。有关详细信息，请参阅交叉引用任意位置。

外部超链接示例

还可以创建指向文档某个部分的链接，并在链接正文中显示自定义文本。当保留包含链接的句子的文本比明确引用被链接部分的标题更重要时，这很有用。

例如，链接到 Sphinx Python Document Generator 主页并生成句子“Click here to learn more about Python Sphinx.”的 RST 如下所示

Click `here <https://sphinx-doc.cn>`_ to learn more about Python
Sphinx.

渲染后如下所示

Click here to learn more about Python Sphinx.

请特别注意反引号后面的下划线。如果您忘记包含它并且这是您第一天使用 RST，您可能会花一整天的时间想知道出了什么问题，而没有意识到您遗漏了该下划线。另外，请特别注意替换文本（在本例中为“here”）与将显式链接与替换文本分开的尖括号之间的空格。没有此空格，链接将无法正确渲染。

链接习惯

根据 Ceph 仍由 Inktank 开发时建立的惯例，Ceph 项目文档的贡献者倾向于使用将 .. _Link Text: ../path 链接放在文档底部，并使用 :ref:`path` 形式的引用链接到它们的约定。之所以首选此约定，是因为它使文档在命令行界面中更具可读性。然而，截至 2023 年，我们对两者没有偏好。使用任何使文本更容易阅读的约定。

不鼓励使用句子的一部分作为超链接，像这样。首选“参见 X”的惯例。以下是一些首选的表达方式

有关详细信息，请参见 docs.ceph.com。
参见 docs.ceph.com。

ReStructured Text 的怪癖

外部链接

使用下面的公式来渲染将读者定向到 Ceph 文档外部地址的链接

`inline text <https://www.foo.com>`_

注意

不要忘记在内联文本和小于号之间包含空格。

不要忘记在最后一个反引号之后包含下划线。

要链接到 Ceph 文档外部的地址，请在内联文本和位于外部地址之前的尖括号之间包含一个空格。这与链接到 Ceph 文档内部位置的内联文本约定恰恰相反。有关此约定的示例，请参阅此处。

如果这看起来不一致且令人困惑，那么您是对的。这是不一致且令人困惑的。

另请参阅“外部超链接示例”。

内部链接

要链接到 Ceph 文档中的某个章节，您必须 (1) 在该章节之前定义一个目标链接，然后 (2) 从文档中的另一个位置链接到该目标。以下是目标和指向这些目标的链接的公式

目标

.. _target:

Title of Targeted Section
=========================

Lorem ipsum...

链接到目标

:ref:`target`

带有内联文本的链接到目标

:ref:`inline text<target>`

注意

“inline text”和紧随其后的尖括号之间没有空格。这与链接到 Ceph 文档外部位置的内联文本约定恰恰相反。如果这看起来不一致且令人困惑，那么您是对的。这是不一致且令人困惑的。

转义单词中的粗体字符

本节解释如何使单词中的某些字母变为粗体，而将单词中的其他字母保持常规（非粗体）。

以下单行段落提供了一个示例

Ceph File System。

在 ReStructured Text 中，以下公式将不起作用

**C**eph **F**ile **S**ystem

必须通过转义字符 (\) 关闭粗体表示法，如下所示

**C**\eph **F**\ile **S**\ystem

由 Ceph 基金会为您呈现

Ceph 文档是由非营利性 Ceph 基金会资助和托管的社区资源。如果您希望支持这项工作和我们的其他努力，请考虑立即加入。