英語

使用 Sphinx 進行核心文件編寫

Linux 核心使用 Sphinx 從 reStructuredText 檔案生成漂亮的文件，這些檔案位於 Documentation 下。 要以 HTML 或 PDF 格式構建文件，請使用 make htmldocs 或 make pdfdocs。 生成的文件位於 Documentation/output 中。

reStructuredText 檔案可能包含指令，用於包含來自原始檔的結構化文件註釋或 kernel-doc 註釋。 通常，這些用於描述程式碼的功能、型別和設計。 kernel-doc 註釋具有一些特殊的結構和格式，但除此之外，它們也被視為 reStructuredText。

最後，有數千個純文字文件檔案散佈在 Documentation 周圍。 隨著時間的推移，其中一些可能會轉換為 reStructuredText，但大部分仍將保留為純文字。

Sphinx 安裝

Documentation/ 檔案當前使用的 ReST 標記旨在與 Sphinx 3.4.3 或更高版本一起構建。

有一個指令碼可以檢查 Sphinx 的要求。 請參閱 檢查 Sphinx 依賴項 以獲取更多詳細資訊。

大多數發行版都隨附 Sphinx，但其工具鏈很脆弱，並且在您的機器上升級它或其他一些 Python 包會導致文件構建中斷的情況並不少見。

避免這種情況的一種方法是使用與您的發行版附帶的版本不同的版本。 為此，建議使用 virtualenv-3 或 virtualenv 將 Sphinx 安裝在虛擬環境中，具體取決於您的發行版如何打包 Python 3。

總而言之，如果您想安裝最新版本的 Sphinx，您應該這樣做

$ virtualenv sphinx_latest
$ . sphinx_latest/bin/activate
(sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt

執行 . sphinx_latest/bin/activate 後，提示符將更改，以指示您正在使用新環境。 如果您開啟一個新的 shell，您需要重新執行此命令才能再次進入虛擬環境，然後再構建文件。

影像輸出

核心文件構建系統包含一個擴充套件，可以處理 GraphViz 和 SVG 格式的影像（請參閱 圖表 & 影像）。

要使其正常工作，您需要安裝 GraphViz 和 ImageMagick 包。 如果未安裝這些軟體包，構建系統仍將構建文件，但不會在輸出中包含任何影像。

PDF 和 LaTeX 構建

當前僅 Sphinx 2.4 及更高版本支援此類構建。

對於 PDF 和 LaTeX 輸出，您還需要 XeLaTeX 版本 3.14159265。

根據發行版，您可能還需要安裝一系列 texlive 軟體包，這些軟體包提供 XeLaTeX 正常工作所需的最小功能集。

HTML 中的數學表示式

一些 ReST 頁面包含數學表示式。 由於 Sphinx 的工作方式，這些表示式是使用 LaTeX 表示法編寫的。 Sphinx 有兩種選擇可以在 html 輸出中呈現數學表示式。 一種是名為 imgmath 的擴充套件，它將數學表示式轉換為影像並將其嵌入到 html 頁面中。 另一種是名為 mathjax 的擴充套件，它將數學渲染委託給具有 JavaScript 功能的 Web 瀏覽器。 前者是 6.1 之前的核心文件的唯一選擇，它需要相當多的 texlive 軟體包，包括 amsfonts 和 amsmath 等。

自核心版本 6.1 以來，無需安裝任何 texlive 軟體包即可構建具有數學表示式的 html 頁面。 有關更多資訊，請參閱 數學渲染器的選擇。

檢查 Sphinx 依賴項

有一個指令碼可以自動檢查 Sphinx 依賴項。 如果它可以識別您的發行版，它還會提供有關您的發行版的安裝命令列的提示

$ ./scripts/sphinx-pre-install
Checking if the needed tools for Fedora release 26 (Twenty Six) are available
Warning: better to also install "texlive-luatex85".
You should run:

        sudo dnf install -y texlive-luatex85
        /usr/bin/virtualenv sphinx_2.4.4
        . sphinx_2.4.4/bin/activate
        pip install -r Documentation/sphinx/requirements.txt

Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.

預設情況下，它會檢查 html 和 PDF 的所有要求，包括影像、數學表示式和 LaTeX 構建的要求，並假定將使用虛擬 Python 環境。 html 構建所需的要求被認為是強制性的； 其他的被認為是可選的。

它支援兩個可選引數

--no-pdf

停用 PDF 的檢查；

--no-virtualenv

對 Sphinx 使用 OS 打包，而不是 Python 虛擬環境。

Sphinx 構建

生成文件的常用方法是執行 make htmldocs 或 make pdfdocs。 還有其他格式可用：請參閱 make help 的文件部分。 生成的文件位於 Documentation/output 下的特定於格式的子目錄中。

要生成文件，必須安裝 Sphinx (sphinx-build)。 對於 PDF 輸出，您還需要 XeLaTeX 和來自 ImageMagick 的 convert(1) (https://www.imagemagick.org)。[1] 所有這些都廣泛可用並打包在發行版中。

要將額外的選項傳遞給 Sphinx，您可以使用 SPHINXOPTS make 變數。 例如，使用 make SPHINXOPTS=-v htmldocs 獲取更詳細的輸出。

還可以傳遞額外的 DOCS_CSS 覆蓋檔案，以便透過使用 DOCS_CSS make 變數來自定義 html 佈局。

預設情況下，“Alabaster”主題用於構建 HTML 文件； 此主題與 Sphinx 捆綁在一起，無需單獨安裝。 可以透過使用 DOCS_THEME make 變數來覆蓋 Sphinx 主題。

注意

有些人可能更喜歡為 html 輸出使用 RTD 主題。 根據 Sphinx 版本，應使用 pip install sphinx_rtd_theme 單獨安裝它。

還有另一個 make 變數 SPHINXDIRS，它在測試構建文件子集時很有用。 例如，您可以透過執行 make SPHINXDIRS=doc-guide htmldocs 來構建 Documentation/doc-guide 下的文件。 make help 的文件部分將向您顯示您可以指定的子目錄列表。

要刪除生成的文件，請執行 make cleandocs。

數學渲染器的選擇

自核心版本 6.1 以來，mathjax 可以作為 html 輸出的備用數學渲染器。[2]

數學渲染器的選擇取決於可用命令，如下所示

HTML 的數學渲染器選擇

數學渲染器

所需命令

影像格式

imgmath

latex, dvipng

PNG (柵格)

mathjax

可以透過設定環境變數 SPHINX_IMGMATH 來覆蓋該選擇，如下所示

設定 SPHINX_IMGMATH 的效果

設定

渲染器

SPHINX_IMGMATH=yes

imgmath

SPHINX_IMGMATH=no

mathjax

編寫文件

新增新文件可以像

  1. 在 Documentation 下的某個位置新增一個新的 .rst 檔案。

  2. 從 Documentation/index.rst 中的 Sphinx 主 TOC 樹中引用它。

對於簡單的文件（比如您現在閱讀的文件），這通常就足夠了，但對於較大的文件，建議建立一個子目錄（或使用現有的子目錄）。 例如，圖形子系統文件位於 Documentation/gpu 下，分為幾個 .rst 檔案，並且有一個單獨的 index.rst（帶有自己的 toctree），該檔案從主索引引用。

有關您可以使用它們做什麼，請參閱 Sphinx 和 reStructuredText 的文件。 特別是，Sphinx reStructuredText Primer 是開始使用 reStructuredText 的好地方。 還有一些 Sphinx 特定標記結構。

核心文件的特定指南

以下是核心文件的一些特定指南

  • 請不要過度使用 reStructuredText 標記。 保持簡單。 在大多數情況下，文件應該是純文字，格式具有足夠的連貫性，可以轉換為其他格式。

  • 將現有文件轉換為 reStructuredText 時，請儘量減少格式更改。

  • 在轉換文件時，還要更新內容，而不僅僅是格式。

  • 請堅持以下標題裝飾順序

    1. = 帶有上劃線，用於文件標題

      ==============
Document title
==============

    2. = 用於章節

      Chapters
========

    3. - 用於節

      Section
-------

    4. ~ 用於小節

      Subsection
~~~~~~~~~~

    儘管 RST 沒有強制規定特定的順序（“而不是強制規定固定數量和順序的節標題裝飾樣式，強制執行的順序將是遇到的順序。”），但讓更高級別保持相同整體可以更容易地遵循文件。

  • 對於插入固定寬度的文字塊（對於程式碼示例、用例示例等），對於任何不能真正從語法突出顯示中受益的內容，尤其是短程式碼段，請使用 ::。 對於可以從突出顯示中受益的較長程式碼塊，請使用 .. code-block:: <language>。 對於嵌入在文字中的短程式碼段，請使用 ``。

C 域

Sphinx C 域（名稱 c）適用於 C API 的文件。 例如，函式原型

.. c:function:: int ioctl( int fd, int request )

kernel-doc 的 C 域有一些其他功能。 例如，您可以使用通用名稱（如 open 或 ioctl）重新命名函式的引用名稱

.. c:function:: int ioctl( int fd, int request )
   :name: VIDIOC_LOG_STATUS

func-name（例如 ioctl）保留在輸出中，但 ref-name 從 ioctl 更改為 VIDIOC_LOG_STATUS。 此函式的索引條目也更改為 VIDIOC_LOG_STATUS。

請注意，無需使用 c:func: 來生成對函式文件的交叉引用。 由於某些 Sphinx 擴充套件魔術，如果給定的函式名稱存在索引條目，則文件構建系統會自動將對 function() 的引用轉換為交叉引用。 如果您在核心文件中看到 c:func: 用法，請隨時將其刪除。

表

ReStructuredText 提供了用於表語法的多個選項。 表的核心樣式是首選簡單表語法或網格表語法。 有關更多詳細資訊，請參閱 reStructuredText 使用者參考中的表語法。

列表表

對於不易在通常的 Sphinx ASCII 藝術格式中佈局的表，列表表格式非常有用。 但是，對於純文字文件的讀者來說，這些格式幾乎不可能理解，因此在沒有充分理由的情況下應避免使用它們。

flat-table 是類似於 list-table 的雙階段列表，具有一些其他功能

  • column-span：使用角色 cspan 可以透過其他列擴充套件單元格

  • row-span：使用角色 rspan 可以透過其他行擴充套件單元格

  • 自動跨越錶行最右邊的單元格到該錶行右側的缺失單元格上。 使用選項 :fill-cells:，此行為可以從自動跨越更改為自動填充，這會自動插入（空）單元格而不是跨越最後一個單元格。

選項

  • :header-rows: [int] 標題行計數

  • :stub-columns: [int] 存根列計數

  • :widths: [[int] [int] ... ] 列的寬度

  • :fill-cells: 而不是自動跨越缺失的單元格，插入缺失的單元格

角色

  • :cspan: [int] 其他列 (morecols)

  • :rspan: [int] 其他行 (morerows)

下面的示例顯示瞭如何使用此標記。 分階段列表的第一級是錶行。 在錶行中，只允許一個標記，即此錶行中的單元格列表。 例外是註釋（..）和目標（例如，對 :ref:`last row <last row>` / 最後一行 的引用）。

.. flat-table:: table title
   :widths: 2 1 1 3

   * - head col 1
     - head col 2
     - head col 3
     - head col 4

   * - row 1
     - field 1.1
     - field 1.2 with autospan

   * - row 2
     - field 2.1
     - :rspan:`1` :cspan:`1` field 2.2 - 3.3

   * .. _`last row`:

     - row 3

渲染為

表格標題

表頭 col 1

表頭 col 2

表頭 col 3

表頭 col 4

行 1

欄位 1.1

具有自動跨越的欄位 1.2

行 2

欄位 2.1

欄位 2.2 - 3.3

行 3

交叉引用

從一個文件頁面到另一個文件頁面的交叉引用可以透過簡單地編寫文件檔案的路徑來完成，無需特殊語法。 該路徑可以是絕對路徑或相對路徑。 對於絕對路徑，請以“Documentation/”開頭。 例如，要交叉引用到此頁面，以下所有選項都是有效的，具體取決於當前文件的目錄（請注意，需要 .rst 副檔名）

See Documentation/doc-guide/sphinx.rst. This always works.
Take a look at sphinx.rst, which is at this same directory.
Read ../sphinx.rst, which is one directory above.

如果您希望連結具有與文件標題不同的渲染文字，則需要使用 Sphinx 的 doc 角色。 例如

See :doc:`my custom link text for document sphinx <sphinx>`.

對於大多數用例，前者是首選，因為它更簡潔，更適合閱讀原始檔的人員。 如果您遇到任何沒有新增任何值的 :doc: 用法，請隨時將其轉換為僅文件路徑。

有關交叉引用 kernel-doc 函式或型別的資訊，請參閱 編寫 kernel-doc 註釋。

引用提交

給定以以下格式之一編寫的 git 提交的引用會自動超連結

commit 72bf4f1767f0
commit 72bf4f1767f0 ("net: do not leave an empty skb in write queue")

圖表 & 影像

如果要新增影像，則應使用 kernel-figure 和 kernel-image 指令。 例如，要插入具有可縮放影像格式的圖形，請使用 SVG (SVG 影像示例)

.. kernel-figure::  svg_image.svg
   :alt:    simple SVG image

   SVG image example
simple SVG image

SVG 影像示例

核心圖形（和影像）指令支援 DOT 格式的檔案，請參閱

一個簡單的示例 (DOT 的 hello world 示例)

.. kernel-figure::  hello.dot
   :alt:    hello world

   DOT's hello world example
hello world

DOT 的 hello world 示例

嵌入的渲染標記（或語言），如 Graphviz 的 DOT 由 kernel-render 指令提供。

.. kernel-render:: DOT
   :alt: foobar digraph
   :caption: Embedded **DOT** (Graphviz) code

   digraph foo {
    "bar" -> "baz";
   }

這將如何呈現取決於已安裝的工具。 如果安裝了 Graphviz，您將看到一個向量影像。 如果沒有，則將原始標記作為文字塊插入 (嵌入的 DOT (Graphviz) 程式碼)。

foobar digraph

嵌入的 DOT (Graphviz) 程式碼

render 指令具有 figure 指令中的所有已知選項，以及選項 caption。 如果 caption 有一個值，則插入一個 figure 節點。 如果沒有，則插入一個 image 節點。 如果要引用它，也需要一個 caption (嵌入的 SVG 標記)。

嵌入的 SVG

.. kernel-render:: SVG
   :caption: Embedded **SVG** markup
   :alt: so-nw-arrow

   <?xml version="1.0" encoding="UTF-8"?>
   <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
      ...
   </svg>
so-nw-arrow

嵌入的 SVG 標記