Sphinx 快速入门模板¶

本文旨在帮助那些“想要编写文档并将其添加到 LLVM 文档中”的人快速开始编写文档，并尽可能减少不必要的麻烦。

概述 ¶

LLVM 文档使用 reStructuredText 编写，这是一种类似于 Markdown 的标记语法（但功能更强大）。LLVM 文档站点本身使用 Sphinx，这是一种最初为 Python 文档编写的文档生成器。

如何使用此模板 ¶

本文位于 docs/SphinxQuickstartTemplate.rst。要将其用作模板，请复制并使用文本编辑器打开它。然后，您可以编写您的文档，并将新文章发送到 llvm-commits 进行审查。

要查看本文的 reStructuredText 源文件，请点击右侧侧边栏上的“显示源代码”。

编写指南 ¶

专注于内容。如有必要，稍后很容易修复 Sphinx (reStructuredText) 语法，尽管 reStructuredText 尝试模仿常见的纯文本约定，因此它应该非常自然。在编写文档时，了解 reStructuredText 语法的基本知识很有用，因此本文的后半部分（从示例章节开始）提供了示例，这些示例应该涵盖 99% 的用例。

让我再说一遍：专注于内容。但如果您确实需要验证 Sphinx 的输出，请参阅 docs/README.txt 以获取信息。完成内容后，请将 .rst 文件发送到 llvm-commits 进行审查。

创建新文章 ¶

在创建新文章之前，请考虑以下问题

我为什么要阅读本文档？
我需要具备哪些知识才能理解本文档？
阅读完本文档后，我将学到什么？

标准最佳实践是使您的文章面向任务。除非您要记录的主题已经有现有的“操作方法”文章，否则通常不应编写与“如何”执行某些操作无关的文档。这样做的原因是，如果没有“操作方法”文章供先阅读，那么不熟悉该主题的人可能难以理解更高级别的概念性文章。

在创建面向任务的文章时，请遵循现有的 LLVM 文章，为其指定一个以 HowTo*.rst 开头的文件名。这种格式通常最容易让人理解，也是最有用的。

专注于内容（是的，我必须再说一遍）。

本文档的其余部分显示了示例 reStructuredText 标记结构，这些结构旨在供您在复制此文件到您即将编写的文档的新文件中后，在您的文本编辑器中阅读。

以 #. 开头的列表将自动编号。
这是第二个列表元素。
1. 使用缩进创建嵌套列表。

…以及无序列表

内容。
- 更深层的内容。
更多内容。

代码块 ¶

您可以像这样创建代码块

int main() {
  return 0;
}

对于 shell 会话，请使用 console 代码块（一些现有文档使用 bash）

$ echo "Goodbye cruel world!"
$ rm -rf /

如果您需要显示 LLVM IR，请使用 llvm 代码块。

define i32 @test1() {
entry:
  ret i32 0
}

您可能需要的其他一些常用代码块包括 c、objc、make 和 cmake。如果您需要超出这些范围的内容，您可以查看支持的代码块的完整列表。

但是，当您可以添加有意义的内容时，不要浪费时间去调整语法高亮。如有疑问，请显示以下格式的文本，而无需任何语法高亮

                      .
                       +:.
                   ..:: ::
                .++:+:: ::+:.:.
               .:+           :
        ::.::..::            .+.
      ..:+    ::              :
......+:.                    ..
      :++.    ..              :
        .+:::+::              :
        ..   . .+            ::
                 +.:      .::+.
                  ...+. .: .
                     .++:..
                      ...

生成文档 ¶

如果您想查看文档的外观，可以从本地源代码生成 HTML 文档。除了正常的构建工具之外，您还需要使用以下命令在 llvm-project 检出中安装 Sphinx 和必要的扩展

pip install --user -r ./llvm/docs/requirements.txt

然后运行 cmake 构建 llvm-project 检出中的文档

mkdir build
cd build
cmake -DLLVM_ENABLE_SPHINX=On ../llvm
cmake --build . --target docs-llvm-html

如果您已经设置了 Cmake 构建并希望重用它，只需设置 CMake 变量 LLVM_ENABLE_SPHINX=On。

之后，您可以在 build/docs/html 文件夹中找到生成的文档。

文档

参与贡献

其他链接

本页

Sphinx 快速入门模板¶

概述 ¶

如何使用此模板 ¶

编写指南 ¶

创建新文章 ¶

示例章节 ¶

示例嵌套子章节 ¶

文本格式 ¶

链接 ¶

列表 ¶

代码块 ¶

生成文档 ¶