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 文档的外观，可以从本地源生成 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 快速入门模板¶

概述 ¶

如何使用此模板 ¶

编写指南 ¶

创建新文章 ¶

示例章节 ¶

示例嵌套小节 ¶

文本格式化 ¶

链接 ¶

列表 ¶

代码块 ¶

生成文档 ¶