Markdown 快速入門範本¶

簡介與快速入門¶

本文檔旨在讓您盡快開始撰寫文件，即使您沒有 Markdown 的使用經驗。目標是讓那些「我想撰寫文件並將其添加到 LLVM 的文檔中」的人，能夠產出有用的文件，並以盡可能簡潔的方式郵寄到 llvm-commits。

您可以在 docs/MarkdownQuickstartTemplate.md 中找到本文檔。您應該複製它，在您的文字編輯器中打開新檔案，撰寫您的文件，然後將新文檔發送到 llvm-commits 進行審閱。

專注於內容。如有必要，稍後可以輕鬆修正 Markdown 語法，儘管 Markdown 試圖模仿常見的純文字慣例，因此應該相當自然。在撰寫文檔時，具備 Markdown 語法的基本知識會很有幫助，因此本文檔的後半部分（從範例章節開始）提供了範例，這些範例應涵蓋 99% 的使用案例。

讓我再說一遍：專注於內容。但如果您真的需要驗證 Sphinx 的輸出，請參閱 docs/README.txt 以獲取資訊。

完成內容後，請將 .md 檔案發送到 llvm-commits 進行審閱。

指南¶

嘗試在您的第一節中回答以下問題

我為什麼要閱讀本文檔？
我應該了解什麼才能跟上本文檔的內容？
在閱讀完本文檔後，我將學到什麼？

第一節的常用名稱是 簡介、概述 或 背景。

如果可能，請將您的文檔製作成「操作指南」。像其他「操作指南」文檔一樣，給它一個 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)

文件

參與貢獻

其他連結

本頁