注意
本文档适用于 Ceph 的开发版本。
文档化 Ceph
用户文档
docs.ceph.com 上的文档是从 Ceph git 仓库中 /doc/ 目录下的 reStructuredText 源文件生成的。
请确保您的更改是以面向软件最终用户的方式编写的，除非您在 /doc/dev/ 中进行添加，该部分是供开发人员使用的。
所有修改面向用户功能的拉取请求都必须包含相应的文档更新：有关详细信息，请参阅 提交补丁。
通过在 github 用户界面中查看 .rst 文件差异时使用“查看”按钮，或者使用 admin/build-doc 脚本在本地构建文档，来检查您的 .rst 语法是否按预期工作。
有关 Ceph 文档的更多信息，请参阅 文档化 Ceph。
代码文档
C 和 C++ 可以使用 Doxygen 进行文档化，并使用 Breathe 支持的 Doxygen 标记子集。
函数文档的一般格式是
/**
* Short description
*
* Detailed description when necessary
*
* preconditions, postconditions, warnings, bugs or other notes
*
* parameter reference
* return value (if non-void)
*/
这应该在声明函数的头文件中，并且函数应该分组到逻辑类别中。librados C API 提供了一个完整的示例。它通过 librados.rst 被拉入 Sphinx，并在 Librados (C) 处呈现。
要以 HTML 格式生成 doxygen 文档，请使用
# cmake --build . --target doxygen
HTML 输出将在：build-doc/doxygen/html 下
绘制图表
Graphviz
您可以使用 Graphviz，如 Graphviz 扩展文档中所述。
大多数情况下，您会希望将实际的 DOT 源代码放在一个单独的文件中，像这样
.. graphviz:: myfile.dot
有关有向图的示例，请参阅 Emden R. Gansner、Eleftherios Koutsofios 和 Stephen North 撰写的 Dot 用户手册。如果您是第一次接触 GraphViz，这将特别有用。
Ditaa
您可以使用 Ditaa
Blockdiag
如果需要，我们可以集成 Blockdiag。它是一种用于绘制图表的 Graphviz 风格声明性语言，包括
Inkscape
您可以使用 Inkscape 生成可缩放矢量图形。适用于 restructuredText 文档的 https://inkscape.org/en/。
如果您使用 Inkscape 生成图表，您应该同时提交可缩放矢量图形 (SVG) 文件并导出一个便携式网络图形 (PNG) 文件。引用 PNG 文件。
通过提交 SVG 文件，其他人将能够使用 Inkscape 更新 SVG 图表。
HTML5 将支持内嵌 SVG。