Markdown 快速入门模板¶

介绍和快速入门¶

本文档旨在让您尽快开始编写文档，即使您之前没有 Markdown 经验。目标是让那些处于“我想编写文档并将其添加到 LLVM 的文档中”状态的人，尽可能少地废话，将其转化为有用的文档并发送到 llvm-commits 邮件列表。

您可以在 docs/MarkdownQuickstartTemplate.md 中找到本文档。您应该复制它，在您的文本编辑器中打开新文件，编写您的文档，然后将新文档发送到 llvm-commits 以供审阅。

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

让我再说一遍：专注于内容。但是，如果您确实需要验证 Sphinx 的输出，请参阅 docs/README.txt 以获取信息。

完成内容后，请将 .md 文件发送到 llvm-commits 以供审阅。

指南¶

尝试在您的第一节中回答以下问题

我为什么要阅读本文档？
我应该了解什么才能跟上本文档的进度？
在本文档结束时，我将学到什么？

第一节的常用名称是 Introduction、Overview 或 Background。

如果可能，请将您的文档制作成“操作指南”。像其他“操作指南”文档一样，给它起一个 HowTo*.md 的名称。这种格式通常最容易让人理解，也最有用。

通常，除非已经有关于您主题的“操作指南”，否则您不应该编写除“操作指南”之外的文档。原因是，如果没有“操作指南”文档供首先阅读，人们很难理解更高级的文档。

专注于内容（是的，我不得不再次说一遍）。

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

示例章节¶

您的文本可以强调、加粗或 等宽。

使用空行分隔段落。

标题（如上面的 示例章节）赋予您的文档结构。

示例子章节¶

创建一个链接，例如这样。还有一种更复杂的语法，对于较长的链接来说，可能更具可读性，因为它对流程的干扰较小。您可以将 [链接名称]: <URL> 块放在文档后面的任何位置。

列表可以像这样制作

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

您也可以使用无序列表。

东西。
- 更深的东西。
更多东西。

示例子子章节¶

您可以像这样创建代码块

int main() {
  return 0;
}

作为 markdown 的扩展，您还可以指定要使用的语法高亮器。

int main() {
  return 0;
}

对于 shell 会话，请使用 console 代码块。

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

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

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

您可能需要的其他一些常见代码块是 c、objc、make 和 cmake。如果您需要超出此范围的东西，您可以查看完整列表的支持代码块。

但是，当您可以添加有意义的内容时，不要浪费时间摆弄语法高亮。如有疑问，请显示没有语法高亮的预格式化文本，如下所示

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

希望您不需要这么深入¶

如果您需要执行比本文档中所示更复杂的操作，您可以发送邮件到邮件列表或查看 Common Mark 规范。Sphinx 特定集成文档可以在 myst-parser 文档中找到。

生成文档¶

请参阅 [Sphinx 快速入门模板](project:SphinxQuickstartTemplate.rst#Generating the documentation)

文档

参与

其他链接

本页