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 快速入門範本¶

概觀 ¶

如何使用此範本 ¶

撰寫準則 ¶

建立新文章 ¶

範例章節 ¶

範例巢狀子章節 ¶

文字格式 ¶

連結 ¶

清單 ¶

程式碼區塊 ¶

產生文件 ¶