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 標記結構，這些結構旨在讓您在將此檔案複製到新檔案以用於您即將撰寫的文件後，在文字編輯器中閱讀。

範例章節 ¶

一篇文章可以包含一個或多個章節（即標題）。章節（如上面的 範例章節）有助於賦予您的文件結構。使用與本文中使用的相同種類的裝飾（例如 ====== 與 ------）。裝飾的長度必須與其上方的文字相同。對於 Vim 使用者，yypVr= 的變體可能很方便。

範例巢狀小節 ¶

小節也可以巢狀於其他小節之下。有關章節的更多資訊，請參閱 Sphinx 的 reStructuredText 入門。

文字格式 ¶

文字可以被強調、粗體或 等寬字體。

要建立新段落，只需插入一個空白行。

連結 ¶

您可以像這樣格式化連結。更複雜的語法允許您將 .. _`連結文字`: <URL> 區塊放置在文件中幾乎任何其他位置。這在連結到特別長的 URL 時很有用。

列表 ¶

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 資料夾中找到產生的文件。

文件

參與貢獻

額外連結

本頁