注意

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

文档化Ceph

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

修改文档的最简单方法是发送电子邮件到ceph-users@ceph.io。在主题行中包含字符串“ATTN: DOCS”或

另一种修改文档的方法是创建拉取请求。针对 Ceph 文档创建拉取请求的说明在做出贡献.

如果这是您第一次改进文档或如果您注意到一个小错误（例如拼写错误或打字错误），发送电子邮件比创建拉取请求更容易。除非您指示 Ceph 上游文档不要为您记功，否则您将因改进而获得认可。

文档在存储库中的位置

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

查看旧的Ceph文档

The https://docs.ceph.com链接默认显示最新版本的文档（例如，如果“Reef”是最新版本，则默认https://docs.ceph.com显示 Reef 的文档），但您可以通过在 URL 中替换版本名称（例如，quincy）为您喜欢的分支名称（例如，reef in https://docs.ceph.com/en/reef/）来查看 Ceph 更旧版本的文档quincy，以创建一个读取https://docs.ceph.com/en/pacific/).

做出贡献

进行文档贡献与进行代码贡献的基本步骤相同，但有一个例外：您必须构建文档源代码而不是编译程序源代码。构建文档源代码的步骤包括以下步骤：

获取源代码

Ceph 文档源代码是一组位于 Ceph 仓库ceph/doc目录中的 ReStructured Text 文件。有关 GitHub 和 Ceph 的详细信息，请参阅参与Ceph社区！.

使用分叉和拉取方法进行文档贡献。为此，您必须：

在本地安装 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账户（如果您还没有账户）。
分叉 Ceph 项目。请参阅https://github.com/ceph/ceph.
将您的 Ceph 分叉克隆到您的本地主机。这创建了一个所谓的“本地工作副本”。

Ceph 文档按组件组织：

Ceph 存储集群：Ceph 存储集群文档位于doc/rados目录中运行此命令。
Ceph 块设备：Ceph 块设备文档位于doc/rbd目录中运行此命令。
Ceph 对象存储：Ceph 对象存储文档位于doc/radosgw目录中运行此命令。
Ceph 文件系统：Ceph 文件系统文档位于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.

Note

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

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

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

如果不存在，请创建您的分支：

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

进行更改

修改文档涉及打开一个 reStructuredText 文件，更改其内容并保存更改。有关语法要求的详细信息，请参阅文档风格指南。

添加文档涉及在doc目录树中创建一个新的 reStructuredText 文件，并使用*.rst扩展名。您还必须包含对文档的引用：超链接或目录条目。顶级目录的index.rst文件通常包含一个目录，您可以在其中添加新文件名。所有文档都必须有一个标题。请参阅标题 for details.

您的新文档不会自动跟踪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

Note

包含build-doc和serve-doc的目录必须包含在PATH环境变量中，以便这些命令能够正常工作。

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

admin/build-doc

扫描外部链接的可访问性，请执行：

admin/build-doc linkcheck

执行admin/build-doc将在build-doc目录。您可能需要在ceph下创建一个ceph/build-doc下创建一个目录以输出 Javadoc 文件：

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

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

重要

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

构建文档集后，您可以在http://localhost:8080/启动 HTTP 服务器以查看它：

admin/serve-doc

您也可以导航到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(企业 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 发行版，默认和epel软件包库中都没有剩余的 python 软件包。因此，使用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/RHEL7 构建。如果您正在更改ditaa。您可以从兼容的所需软件包中检索并手动安装它们。要在 CentOS/RHEL7 上运行ditaa图表，以便在提交新的或修改的ditaa图表之前验证它们是否正确渲染，您必须安装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 文档提交很简单，但遵循严格的约定：

每个提交应有一个文件（这简化了回滚）。您可以提交多个具有相关更改的文件。不相关的更改不应放在同一个提交中。
提交必须有一个注释。
提交注释必须以doc:。（严格）
注释摘要必须只有一行。（严格）
额外注释可以跟随摘要后的空行，但应简洁。
提交可以包含Fixes: https://tracker.ceph.com/issues/{bug number}.
提交必须包含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提供了一个图形界面，用于查看您的未提交更改、暂存它们以供提交、提交更改并将它们推送到您的分叉 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

最后，选择文件->启动 git gui以激活图形用户界面。

推送更改

提交一个或多个提交后，您必须将它们从本地仓库副本推送到github。像git-gui这样的图形工具提供了一个用户界面，用于向仓库推送。如果您之前创建了分支：

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

否则：

git push

创建拉取请求

如前所述，您可以使用分叉和拉取方法进行文档贡献。

合并额外提交

每个拉取请求都应该只与单个提交相关。如果您在您正在工作的功能分支上进行了多个提交，您需要“合并”这些多个提交。“合并”是“交互式变基”的非正式术语。合并可以通过许多方式完成，但这里的示例将处理一个存在三个提交且所有三个提交中的更改都保留的情况。这三个提交将被合并为一个提交。

进行您稍后要合并的提交。

进行第一个提交。

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分支变基：
```
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)

通知我们

如果一段时间过去了，您提出的拉取请求还没有被审查，请联系组件负责人，询问为什么这么慢。请参阅Component Team Leads以获取组件负责人的列表。

文档风格指南

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

less doc/architecture.rst

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

标题

文档标题：文档标题使用=字符上划线和下划线，标题文本行前后有空格。请参阅文档标题 for details.
部分部分标题使用=字符下划线，文本前后没有空格。在部分标题之前应有两条换行符（除非有一个内联引用在它之前）。请参阅部分详细信息。
子部分标题：子部分标题使用_字符下划线，文本前后没有空格。在子部分标题之前应有两条换行符（除非有一个内联引用在它之前）。

正文

作为一般规则，我们更喜欢文本在列 80 处换行，以便它在命令行界面中可读，前后没有空格。在可能的情况下，我们更喜欢使用文本、列表、原始文本（允许例外）、表格和ditaa图形保持这种约定。

段落: 段落有一个前导和尾随换行符，宽度应不超过 80 个字符，以便文档可以在命令行终端中以原始格式阅读。
原始文本：要创建原始文本示例（例如，命令行用法），请以::或在前面段落后输入换行符以创建空行；然后，在单独的行上输入:: on a separate line followed by another empty line. Then, begin the literal text with tab indentation (preferred) or space indentation of 3 characters.
缩进文本：缩进文本，如项目符号（例如，- some text）可以跨越多行。后续行的文本应与缩进文本的文本开始于相同的字符位置（减少数字、项目符号等）。

缩进文本可以包含原始文本示例。虽然文本缩进应使用空格完成，但原始文本示例应使用制表符缩进。这种约定使您能够通过留出空行并以空间缩进来开始后续段落来添加一个额外的缩进段落。
编号列表：编号列表应使用自动编号，以#.而不是实际数字开始编号缩进，以便编号段落可以重新定位而无需手动重新编号。
代码示例：Ceph 支持使用.. code-block::<language>角色，以便您可以将高亮显示添加到源代码示例中。这对于源代码是首选的。但是，如果将此标签用作编号列表中的示例，则自动编号将重新开始为 1。请参阅显示代码示例 for details.

段落级标记

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

提示：使用.. tip::指令提供额外的信息，以帮助读者或引导读者避开麻烦。
Note: 使用.. note::指令突出显示一个重要点。
重要：使用.. important::指令突出显示重要要求或注意事项（例如，任何可能导致数据丢失的内容）。由于它以红色呈现，因此应谨慎使用此指令。
版本添加：使用.. versionadded::指令用于新功能或配置设置，以便用户知道使用该功能的最小版本。
版本更改：使用.. versionchanged::指令用于使用或配置设置的更改。
已弃用：使用.. deprecated::指令当 CLI 使用、功能或配置设置不再推荐或将被弃用时。
主题：使用.. topic::指令封装文档中主流程之外的文本。请参阅主题指令以获取更多详细信息。

目录和超链接

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

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

Ceph 项目使用.. toctree::指令。请参阅The TOC tree详细信息。在渲染目录（TOC）时，指定:maxdepth:参数，以便渲染的 TOC 不会太长。

使用:ref:语法，其中链接目标包含一个特定的唯一标识符（例如，.. _unique-target-id:）。指向指定部分的链接.. _unique-target-id:如下所示：:ref:`unique-target-id`。如果遵循此约定，即使源文件在.rst source files will work even if the source files are moved within the ceph/doc目录内移动，源文件内的链接也能正常工作。请参阅随机位置交叉引用详细信息。

外部超链接示例

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

例如，链接到 Sphinx Python 文档生成器主页的 RST 生成一个句子阅读“点击此处了解更多关于 Python Sphinx。”看起来像这样：

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

这里是渲染后的样子：

点击这里了解更多关于 Python Sphinx。

特别注意下划线后的部分。如果您忘记包含它并且这是您第一天使用 RST，您可能会花一整天的时间想知道出了什么问题，而不知道您遗漏了那个下划线。此外，请特别关注替换文本（在这种情况下，“这里”）和设置显式链接与替换文本之间的空格。如果没有这个空格，链接将无法正确渲染。

链接惯例

当 Ceph 仍然由 Inktank 开发时，为 Ceph 项目文档的贡献者更喜欢使用将.. _Link Text: ../path链接放在文档底部的惯例，并使用:ref:`path`形式的引用链接到它们。这种惯例之所以被偏爱，是因为它使文档在命令行界面中更易于阅读。然而，到 2023 年，我们并没有偏好哪一个。使用哪种惯例使文本更容易阅读。

使用句子的一部分作为超链接，如此，是不鼓励的。写“See X”的惯例是首选的。这里有一些首选的表述：

更多信息，请参阅docs.ceph.com.
请参阅docs.ceph.com.

ReStructured Text 的特性

外部链接

使用以下公式渲染指向 Ceph 文档外部地址的链接：

`inline text <http:www.foo.com>`_

Note

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

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

要链接到 Ceph 文档外部的地址，请在行内文本和前面指向外部地址的尖括号之间包含空格。这是与行内文本链接到 Ceph 文档内部位置的约定完全相反。请参阅这里以获取示例。

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

参考“外部超链接示例”。

内部链接

要链接到 Ceph 文档中的某个部分，您必须（1）在部分之前定义一个目标链接，然后（2）从文档中的另一个位置链接到该目标。以下是目标和链接到这些目标的公式：

目标：

.. _target:

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

Lorem ipsum...

链接到目标：

:ref:`target`

带行内文本链接到目标：

:ref:`inline text<target>`

Note

“行内文本”和它立即后面的尖括号之间没有空格。这恰恰与链接到 Ceph 文档外部位置的行内文本的约定相反。如果这看起来不一致和令人困惑，那么您是对的。它确实不一致和令人困惑。

词语中粗体字符的转义

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

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

CephFileSystem.

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

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

加粗的表示必须通过转义字符（\）关闭，如下所示：

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

由 Ceph 基金会带给您

Ceph 文档是一个社区资源，由非盈利的 Ceph 基金会资助和托管Ceph Foundation. 如果您想支持这一点和我们的其他工作，请考虑加入现在加入.