`sphinx.ext.autosummary` – 產生 autodoc 摘要¶

在 0.6 版本中新增。

此擴充功能產生函式/方法/屬性摘要列表，類似於 Epydoc 和其他 API 文件產生工具輸出的摘要列表。當您的 docstring 冗長且詳細，並且將每個 docstring 放在不同的頁面上使其更易於閱讀時，此功能特別有用。

sphinx.ext.autosummary 擴充功能透過兩個部分完成此操作

有一個 autosummary 指令，用於產生摘要列表，其中包含指向已文件化項目的連結，以及從其 docstring 中提取的簡短摘要。
autosummary 指令也會為其內容中列出的項目產生簡短的「骨架」檔案。這些檔案預設僅包含對應的 sphinx.ext.autodoc 指令，但可以使用範本進行自訂。

sphinx-autogen 腳本也可以從命令列產生「骨架」檔案。

.. autosummary::¶

插入一個表格，其中包含指向已文件化項目的連結，以及每個項目的簡短摘要（docstring 的第一句話）。

autosummary 指令也可以選擇作為包含項目的 toctree 條目。選擇性地，當 autosummary_generate 為 True 時，也可以自動產生這些項目的骨架 .rst 檔案。

例如，

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

產生如下表格

`environment.BuildEnvironment`(app)	翻譯 ReST 檔案的環境。
`util.relative_uri`(base, to)	從 `base` 到 `to` 傳回相對 URL。

Autosummary 使用與 autodoc 相同的 autodoc-process-docstring 和 autodoc-process-signature 鉤子預處理 docstring 和簽名。

選項

:class: class names （類別名稱列表，以空格分隔）¶: 將類別屬性指派給表格。這是一個常用選項。

在 8.2 版本中新增。

:toctree: 選用目錄名稱¶

如果您希望 autosummary 表格也作為 toctree 條目，請使用 toctree 選項，例如

.. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

toctree 選項也向 sphinx-autogen 腳本發出訊號，表示應為此指令中列出的項目產生骨架頁面。此選項接受目錄名稱作為引數；sphinx-autogen 預設會將其輸出放置在此目錄中。如果未提供任何引數，則輸出會放置在與包含指令的檔案相同的目錄中。

在 0.6 版本中新增。

:caption: ToC 的標題¶: 為 toctree 新增標題。

在 3.1 版本中新增。

:signatures: 格式¶

如何顯示簽名。有效值為

long (預設)：使用長簽名。這仍然會被截斷，因此名稱加上簽名不會超過特定長度。
short：如果函式和類別簽名有引數，則顯示為 (…)，如果沒有引數，則顯示為 ()。
none：不顯示簽名。

在 8.2 版本中新增。

:nosignatures:¶

摘要中不顯示函式簽名。

這等同於 :signatures: none。

在 0.6 版本中新增。

在 8.2 版本中變更：此指令選項已被更通用的 :signatures: none 取代。

它將在未來版本的 Sphinx 中被棄用和移除。

:template: 檔案名稱¶

指定用於呈現摘要的自訂範本。例如，

.. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment

將使用您 templates_path 中的範本 mytemplate.rst 來產生所有列出項目的頁面。請參閱下方的自訂範本。

在 1.0 版本中新增。

:recursive:¶

以遞迴方式為模組和子套件產生文件。例如，

.. autosummary::
   :recursive:

   sphinx.environment.BuildEnvironment

在 3.1 版本中新增。

sphinx-autogen – 產生 autodoc 骨架頁面¶

可以使用 sphinx-autogen 腳本，方便地為 autosummary 列表中包含的項目產生骨架文件頁面。

例如，命令

$ sphinx-autogen -o generated *.rst

將讀取設定了 :toctree: 選項的 *.rst 檔案中的所有 autosummary 表格，並在目錄 generated 中為所有已文件化的項目輸出對應的骨架頁面。預設情況下，產生的頁面包含以下形式的文字

sphinx.util.relative_uri
========================

.. autofunction:: sphinx.util.relative_uri

如果未提供 -o 選項，則腳本會將輸出檔案放置在 :toctree: 選項中指定的目錄中。

如需更多資訊，請參閱 sphinx-autogen 文件

自動產生骨架頁面¶

如果您不想使用 sphinx-autogen 建立骨架頁面，您也可以使用這些設定值

autosummary_context¶

類型:: dict[str, Any]
預設:: {}

要傳遞到範本引擎環境以用於 autosummary 骨架檔案的值字典。

在 3.1 版本中新增。

autosummary_generate¶

類型:: bool
預設:: True

布林值，指示是否掃描所有找到的文件以尋找 autosummary 指令，並為每個指令產生骨架頁面。

也可以是要為其產生骨架頁面的文件列表。

新檔案將放置在指令的 :toctree: 選項中指定的目錄中。

在 2.3 版本中變更：發出 autodoc-skip-member 事件，如同 autodoc 一樣。

在 4.0 版本中變更：預設啟用。

autosummary_generate_overwrite¶

類型:: bool
預設:: True

如果為 true，autosummary 會將現有檔案覆寫為產生的骨架頁面。

在 3.0 版本中新增。

autosummary_mock_imports¶

類型:: list[str]
預設:: []

此值包含要模擬的模組列表。如需更多詳細資訊，請參閱 autodoc_mock_imports。它預設為 autodoc_mock_imports。

在 2.0 版本中新增。

autosummary_imported_members¶

類型:: bool
預設:: False

布林旗標，指示是否記錄在模組中匯入的類別和函式。

在 2.1 版本中新增。

在 4.4 版本中變更：如果 autosummary_ignore_module_all 為 False，則對於 __all__ 中列出的成員，會忽略此設定值。

autosummary_ignore_module_all¶

類型:: bool
預設:: True

如果 False 且模組設定了 __all__ 屬性，則 autosummary 會記錄 __all__ 中列出的每個成員，而不會記錄其他成員。

請注意，如果匯入的成員列在 __all__ 中，則無論 autosummary_imported_members 的值為何，都會記錄該成員。若要符合 from module import * 的行為，請將 autosummary_ignore_module_all 設定為 False，並將 autosummary_imported_members 設定為 True。

在 4.4 版本中新增。

autosummary_filename_map¶

類型:: dict[str, str]
預設:: {}

將物件名稱對應到檔案名稱的 dict。這對於避免檔案名稱衝突是必要的，在檔案系統不區分大小寫的情況下，當忽略大小寫時，多個物件的名稱無法區分。

在 3.2 版本中新增。

自訂範本¶

在 1.0 版本中新增。

您可以自訂骨架頁面範本，方式與 HTML Jinja 範本類似，請參閱範本化。（不支援 TemplateBridge。）

注意

如果您發現自己花費大量時間調整骨架範本，這可能表示最好改為撰寫自訂敘述性文件。

Autosummary 使用下列 Jinja 範本檔案

autosummary/base.rst – 回退範本
autosummary/module.rst – 模組範本
autosummary/class.rst – 類別範本
autosummary/function.rst – 函式範本
autosummary/attribute.rst – 類別屬性範本
autosummary/method.rst – 類別方法範本

下列變數在範本中可用

name¶: 已文件化物件的名稱，不包括模組和類別部分。

objname¶: 已文件化物件的名稱，不包括模組部分。

fullname¶: 已文件化物件的完整名稱，包括模組和類別部分。

objtype¶: 已文件化物件的類型，可以是 "module"、"function"、"class"、"method"、"attribute"、"data"、"object"、"exception"、"newvarattribute"、"newtypedata"、"property" 其中之一。

module¶: 已文件化物件所屬模組的名稱。

class¶: 已文件化物件所屬類別的名稱。僅適用於方法和屬性。

underline¶: 包含 len(full_name) * '=' 的字串。請改用 underline 篩選器。

members¶: 包含模組或類別所有成員名稱的列表。僅適用於模組和類別。

inherited_members¶: 包含類別所有繼承成員名稱的列表。僅適用於類別。

在 1.8.0 版本中新增。

functions¶: 包含模組中「公開」函式名稱的列表。此處，「公開」表示名稱不是以下底線開頭。僅適用於模組。

classes¶: 包含模組中「公開」類別名稱的列表。僅適用於模組。

exceptions¶: 包含模組中「公開」例外狀況名稱的列表。僅適用於模組。

methods¶: 包含類別中「公開」方法名稱的列表。僅適用於類別。

attributes¶: 包含類別/模組中「公開」屬性名稱的列表。僅適用於類別和模組。

在 3.1 版本中變更：支援模組的屬性。

modules¶: 包含套件中「公開」模組名稱的列表。僅適用於作為套件且 recursive 選項開啟的模組。

在 3.1 版本中新增。

此外，以下篩選器可用

escape(s)¶: 逸出文字中的任何特殊字元，以用於格式化 RST 環境。例如，這可防止星號將內容設為粗體。這取代了內建的 Jinja escape 篩選器，該篩選器執行 html 逸出。

underline(s, line='='): 為一段文字新增標題底線。

例如，{{ fullname | escape | underline }} 應用於產生頁面的標題。

注意

您可以在骨架頁面中使用 autosummary 指令。骨架頁面也是根據這些指令產生的。

sphinx.ext.autosummary – 產生 autodoc 摘要¶

sphinx-autogen – 產生 autodoc 骨架頁面¶

自動產生骨架頁面¶

自訂範本¶

`sphinx.ext.autosummary` – 產生 autodoc 摘要¶