sphinx.ext.autodoc – 包含來自 docstrings 的文件

此擴充功能可以導入您正在文件化的模組，並以半自動方式從 docstrings 中提取文件。

警告

autodoc 導入要文件化的模組。如果任何模組在導入時有副作用，這些副作用將在執行 sphinx-build 時由 autodoc 執行。

如果您要文件化腳本（而不是程式庫模組），請確保主常式受到 if __name__ == '__main__' 條件的保護。

為了使此功能正常運作，docstrings 當然必須以正確的 reStructuredText 撰寫。然後您可以在 docstrings 中使用所有常用的 Sphinx 標記，並且它將正確地呈現在文件中。結合手寫文件，此技術減輕了維護兩個文件位置的痛苦，同時避免了看起來像是自動產生的純 API 文件。

如果您偏好 NumPy 或 Google 風格的 docstrings 而非 reStructuredText，您也可以啟用 napoleon 擴充功能。napoleon 是一個預處理器，可在 autodoc 處理 docstrings 之前將其轉換為正確的 reStructuredText。

開始使用

設定

透過將 'sphinx.ext.autodoc' 新增到 conf.py 中的 extensions 列表來啟用外掛程式

extensions = [
    ...
    'sphinx.ext.autodoc',
]

確保程式碼可以被導入

autodoc 在 導入模組 後，透過內省分析程式碼和 docstrings。為了使導入工作正常運作，您必須確保 Sphinx 可以找到您的模組，並且可以解析相依性（如果您的模組執行 import foo，但 foo 在 Sphinx 執行的 python 環境中不可用，則您的模組導入將會失敗）。

有兩種方法可以確保這一點

  1. 使用包含您的套件和 Sphinx 的環境。例如，這可以是您的本機開發環境（使用可編輯的安裝），或 CI 中安裝 Sphinx 和您的套件的環境。常規安裝程序可確保 Sphinx 可以找到您的套件，並且所有相依性都可用。

  2. 或者，也可以修補 Sphinx 執行，使其可以直接在來源上運作；例如，如果您希望能夠從來源簽出執行 Sphinx 建置。

    • 修補 conf.py 中的 sys.path 以包含您的來源路徑。例如，如果您的儲存庫結構具有 doc/conf.py 並且您的套件位於 src/my_package，則您應該將以下內容新增到您的 conf.py。

      import sys
from pathlib import Path

sys.path.insert(0, str(Path('..', 'src').resolve()))

    • 為了處理遺失的相依性，請在 autodoc_mock_imports 設定中指定遺失的模組。

用法

您現在可以使用 指令 為 Python 程式碼元素（如函式、類別、模組等）新增格式化的文件。例如，為了文件化函式 io.open()，從原始檔讀取其簽名和 docstring，您可以撰寫

.. autofunction:: io.open

您也可以使用自動指令的成員選項，自動文件化整個類別甚至模組，例如

.. automodule:: io
   :members:

提示

作為 autodoc 擴充功能的提示，您可以在模組名稱和物件名稱之間放置 :: 分隔符號，以讓 autodoc 知道正確的模組（如果模稜兩可）

.. autoclass:: module.name::Noodle

將物件標記為公開或私有

  • 如果成員的 docstring 在其 資訊欄位列表 中包含 :meta private:，則 autodoc 會將其視為私有。例如

    def my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta private:
    """

    在版本 3.0 中新增。

  • 如果成員的 docstring 在其 資訊欄位列表 中包含 :meta public:，即使它以底線開頭，autodoc 也會將其視為公開。例如

    def _my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta public:
    """

    在版本 3.1 中新增。

  • 如果變數成員的 docstring 在其 資訊欄位列表 中包含 :meta hide-value:，則 autodoc 會認為該成員沒有任何預設值。範例

    var1 = None  #: :meta hide-value:

    在版本 3.5 中新增。

文件註解與 docstrings

Python 沒有內建支援模組資料成員或類別屬性的 docstrings。為了允許文件化這些內容，autodoc 識別了一種特殊的 註解 格式，稱為「文件註解」或「documentation comment」。

這些註解以冒號和一個可選的空格字元開頭，'#:' 或 '#: '。為了被識別，註解必須出現在與變數相同的行上，或在變數之前的一行或多行上。多行文件註解必須始終出現在變數定義之前的行上。

例如，以下所有三個變數都具有有效的文件註解

egg_and_spam = 1.50  #: A simple meal

#: Spam! Lovely spam! Lovely spam!
egg_bacon_sausage_and_spam = 2.49

#: Truly gourmet cuisine for madam; Lobster Thermidor
#: aux Crevettes with a mornay sauce garnished with
#: truffle pate, brandy and a fried egg on top and spam.
lobster_thermidor = 35.00

或者，autodoc 可以識別緊接在定義之後的行上的 docstring。

在以下類別定義中，所有屬性都具有 autodoc 識別的文件

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

指令

autodoc 提供了幾個指令，這些指令是常用 py:module、py:class 等的變體。在剖析時，它們會導入對應的模組並提取給定物件的 docstring，將它們插入到頁面來源中，放在適當的 py:module、py:class 等指令下。

注意

就像 py:class 尊重目前的 py:module 一樣，autoclass 也會這樣做。同樣地，automethod 也會尊重目前的 py:class。

預設指令選項

若要將以下描述的任何選項設為預設值，請使用 conf.py 中的 autodoc_default_options 字典。

如果針對 :members:、:exclude-members:、:private-members: 或 :special-members: 選項使用預設值，則在指令上設定選項將會覆寫預設值。相反地，若要使用每個指令的選項擴充預設列表，可以在列表前面加上加號 (+)，如下所示

.. autoclass:: Noodle
   :members: eat
   :private-members: +_spicy, _garlickly

提示

如果使用 autodoc_default_options，則可以使用否定形式 :no-option: 作為指令的選項，來停用每個指令的預設值。例如

.. automodule:: foo
   :no-undoc-members:

自動文件化模組

.. automodule::

文件化模組。預設情況下，指令只會插入模組本身的 docstring

.. automodule:: noodles

將產生如下的來源

.. py:module:: noodles

   The noodles module.

該指令也可以包含自己的內容，這些內容將在 docstring 之後（但在任何自動成員文件之前）插入到產生的非自動指令來源中。

因此，您也可以混合自動和非自動成員文件，如下所示

.. automodule:: noodles
   :members: Noodle

   .. py:function:: boiled_noodle(time=10)

      Create a noodle that has been boiled for *time* minutes.

選項

:no-index:

不要為文件化的模組或任何自動文件化的成員產生索引條目。

在版本 0.4 中新增。

:no-index-entry:

不要為文件化的模組或任何自動文件化的成員產生索引條目。與 :no-index: 不同，交叉參照仍然會建立。

在版本 8.2 中新增。

:platform: platforms (逗號分隔列表)

指示模組可用的平台。這與 py:module 的 :platform: 選項相同。

:synopsis: purpose (文字)

描述模組用途的句子。這與 py:module 的 :synopsis: 選項相同。

在版本 0.5 中新增。

:deprecated:

將模組標記為已棄用。這與 py:module 的 :deprecated: 選項相同。

在版本 0.5 中新增。

:ignore-module-all: (無值)

在分析要文件化的模組時，不要使用 __all__。

在版本 1.7 中新增。

用於選取要文件化成員的選項

:members: (無值或逗號分隔列表)

為目標模組的所有成員產生自動文件

.. automodule:: noodles
   :members:

預設情況下，autodoc 僅包含具有 docstring 或 文件註解 (#:) 的公開成員。如果 __all__ 存在，除非設定了 :ignore-module-all: 選項，否則將使用它來定義哪些成員是公開的。

若要僅文件化某些成員，可以使用明確的逗號分隔列表作為 :members: 的引數

.. automodule:: noodles
   :members: Noodle
:exclude-members: (逗號分隔列表)

從要文件化的成員中排除給定的名稱。例如

.. automodule:: noodles
   :members:
   :exclude-members: NoodleBase

在版本 0.6 中新增。

:imported-members: (無值)

為了防止文件化導入的類別或函式，在設定了 members 選項的 automodule 指令中，只會文件化 __module__ 屬性等於給定給 automodule 的模組名稱的模組成員。

如果您想要防止此行為並文件化所有可用的成員，請設定 imported-members 選項。

請注意，來自導入模組的屬性將不會被文件化，因為屬性文件是透過剖析目前模組的原始檔來探索的。

在版本 1.2 中新增。

:undoc-members:

為目標模組中沒有 docstring 或文件註解的成員產生自動文件。例如

.. automodule:: noodles
   :members:
   :undoc-members:
:private-members: (無值或逗號分隔列表)

為目標模組的私有成員產生自動文件。這包括帶有前導底線的名稱（例如 _private）以及使用 :meta private: 明確標記為私有的成員。

.. automodule:: noodles
   :members:
   :private-members:

若要僅文件化某些私有成員，可以使用明確的逗號分隔列表作為 :private-members: 的引數

.. automodule:: noodles
   :members:
   :private-members: _spicy, _garlickly

在版本 1.1 中新增。

在版本 3.2 中變更: 此選項現在可以接受逗號分隔的引數列表。

:special-members: (無值或逗號分隔列表)

為目標模組的特殊成員產生自動文件，也稱為 「dunder」名稱。這包括所有用雙底線括起來的名稱，例如 __special__

.. automodule:: my.Class
   :members:
   :special-members:

若要僅文件化某些特殊成員，可以使用明確的逗號分隔列表作為 :special-members: 的引數

.. automodule:: noodles
   :members:
   :special-members: __version__

在版本 1.1 中新增。

在版本 1.2 中變更: 此選項現在可以接受逗號分隔的引數列表。

用於文件化成員的選項

:member-order: (alphabetical、bysource 或 groupwise)

選擇自動文件化成員的排序方式（預設值：alphabetical）。這會覆寫 autodoc_member_order 設定。

  • alphabetical：使用簡單的字母順序。

  • groupwise：按物件類型（類別、函式等）分組，在群組內使用字母順序。

  • bysource：使用物件在模組原始碼中的順序。__all__ 變數可用於覆寫此順序。

請注意，對於原始碼順序，模組必須是原始碼可用的 Python 模組。

在版本 0.6 中新增。

在版本 1.0 中變更: 支援 'bysource' 選項。

:show-inheritance: (無值)

如果啟用 :members:，則為模組的所有成員啟用 :show-inheritance: 選項。

在版本 0.4 中新增。

自動文件化類別或例外

.. autoclass::
.. autoexception::

文件化類別。對於例外類別，建議使用 .. autoexception::。預設情況下，指令只會插入類別本身的 docstring

.. autoclass:: noodles.Noodle

將產生如下的來源

.. py:class:: Noodle

   The Noodle class's docstring.

該指令也可以包含自己的內容，這些內容將在 docstring 之後（但在任何自動成員文件之前）插入到產生的非自動指令來源中。

因此，您也可以混合自動和非自動成員文件，如下所示

.. autoclass:: noodles.Noodle
   :members: eat, slurp

   .. py:method:: boil(time=10)

      Boil the noodle for *time* minutes.

進階用法

  • 可以覆寫明確文件化的可呼叫物件（函式、方法、類別）的簽名，使用常規語法，這將覆寫從內省獲得的簽名

    .. autoclass:: noodles.Noodle(type)

   .. automethod:: eat(persona)

    如果方法的簽名被裝飾器隱藏，這會很有用。

    在版本 0.4 中新增。

選項

:no-index:

不要為文件化的類別或任何自動文件化的成員產生索引條目。

在版本 0.4 中新增。

:no-index-entry:

不要為文件化的類別或任何自動文件化的成員產生索引條目。與 :no-index: 不同，交叉參照仍然會建立。

在版本 8.2 中新增。

:class-doc-from: (class、init 或 both)

選取哪個 docstring 將用於指令的主體。這會覆寫 autoclass_content 的全域值。可能的值為

  • class：僅使用類別的 docstring。__init__() 方法可以使用 :members: 選項或 automethod 單獨文件化。

  • init：僅使用 __init__() 方法的 docstring。

  • both：同時使用兩者，將 __init__() 方法的 docstring 附加到類別的 docstring。

如果 __init__() 方法不存在或具有空白的 docstring，autodoc 將嘗試使用 __new__() 方法的 docstring，如果該 docstring 存在且非空白。

版本 4.1 新增。

用於選取要文件化成員的選項

:members: （無 值 或 逗號分隔列表）

為目標類別的所有成員產生自動文件

.. autoclass:: noodles.Noodle
   :members:

預設情況下，autodoc 僅包含具有 docstring 或 doc-comment (#:) 的公開成員，且這些成員是目標類別的屬性（即，非繼承的）。

若要僅文件化某些成員，可以使用明確的逗號分隔列表作為 :members: 的引數

.. autoclass:: noodles.Noodle
   :members: eat, slurp
:exclude-members: （逗號分隔列表）

從要文件化的成員中排除給定的名稱。例如

.. autoclass:: noodles.Noodle
   :members:
   :exclude-members: prepare

在版本 0.6 中新增。

:inherited-members: （逗號分隔列表）

若要為從基底類別繼承的成員產生自動文件，請使用 :inherited-members: 選項

.. autoclass:: noodles.Noodle
   :members:
   :inherited-members:

這可以與 :undoc-members: 選項結合使用，以為類別的所有可用成員產生自動文件。

在 :inherited-members: 的參數中列出的類別成員將從自動文件中排除。如果未提供任何參數，則預設為 object，這表示 object 類別的成員不會被記錄。若要包含這些成員，請使用 None 作為參數。

例如；如果您的類別 MyList 衍生自 list 類別，且您不想記錄 list.__len__()，則應指定選項 :inherited-members: list 以避免 list 類別的特殊成員。

注意

如果任何繼承的成員對其 docstring 使用 reStructuredText 以外的格式，則可能會出現標記警告或錯誤。

版本 0.3 新增。

版本 3.0 變更：:inherited-members: 現在接受要排除的基底類別名稱作為參數。

版本 5.0 變更：可以使用逗號分隔的基底類別名稱列表。

:undoc-members: （無 值）

為目標類別中沒有 docstring 或 doc-comment 的成員產生自動文件。例如

.. autoclass:: noodles.Noodle
   :members:
   :undoc-members:
:private-members: （無 值 或 逗號分隔列表）

為目標類別的私有成員產生自動文件。這包括帶有前導底線的名稱（例如 _private）以及使用 :meta private: 明確標記為私有的成員。

.. autoclass:: noodles.Noodle
   :members:
   :private-members:

若要僅文件化某些私有成員，可以使用明確的逗號分隔列表作為 :private-members: 的引數

.. autoclass:: noodles.Noodle
   :members:
   :private-members: _spicy, _garlickly

在版本 1.1 中新增。

版本 3.2 變更：此選項現在可以接受參數。

:special-members: （無 值 或 逗號分隔列表）

為目標類別的特殊成員產生自動文件，也稱為 「dunder」名稱。這包括所有以雙底線括起來的名稱，例如 __special__

.. autoclass:: noodles.Noodle
   :members:
   :special-members:

若要僅文件化某些特殊成員，可以使用明確的逗號分隔列表作為 :special-members: 的引數

.. autoclass:: noodles.Noodle
   :members:
   :special-members: __init__, __name__

在版本 1.1 中新增。

在版本 1.2 中變更: 此選項現在可以接受逗號分隔的引數列表。

用於文件化成員的選項

:member-order: （alphabetical、 bysource 或 groupwise）

選擇自動文件化成員的排序方式（預設值：alphabetical）。這會覆寫 autodoc_member_order 設定。

  • 'alphabetical'：使用簡單的字母順序。

  • 'groupwise'：依物件類型（類別、函數等）分組，在群組內使用字母順序。

  • 'bysource'：使用成員在模組原始碼中出現的順序。__all__ 變數可用於覆寫此順序。

請注意，對於原始碼順序，模組必須是原始碼可用的 Python 模組。

在版本 0.6 中新增。

在版本 1.0 中變更: 支援 'bysource' 選項。

:show-inheritance: （無 值）

在類別簽名後插入類別的基底類別。

在版本 0.4 中新增。

自動記錄函式型物件的文件

.. autofunction::
.. automethod::
.. autoproperty::
.. autodecorator::

記錄函式、方法、屬性或裝飾器的文件。預設情況下，此指令僅插入函式本身的 docstring

.. autofunction:: noodles.average_noodle

將產生如下的來源

.. py:function:: noodles.average_noodle

   The average_noodle function's docstring.

此指令也可以包含其自身的內容，這些內容將在 docstring 之後插入到產生的非自動指令來源中。

因此，您也可以混合自動和非自動文件，如下所示

.. autofunction:: noodles.average_noodle

   .. note:: For more flexibility, use the :py:class:`!Noodle` class.

版本 2.0 新增：autodecorator。

版本 2.1 新增：autoproperty。

注意

如果您要記錄裝飾過的函式或方法，請記住 autodoc 會透過匯入模組並檢查給定函式或方法的 __doc__ 屬性來擷取其 docstring。這表示如果裝飾器將裝飾過的函式替換為另一個函式，則必須將原始 __doc__ 複製到新函式。

進階用法

  • 可以覆寫明確文件化的可呼叫物件（函式、方法、類別）的簽名，使用常規語法，這將覆寫從內省獲得的簽名

    .. autoclass:: Noodle(type)

   .. automethod:: eat(persona)

    如果方法的簽名被裝飾器隱藏，這會很有用。

    在版本 0.4 中新增。

選項

:no-index:

不要為記錄的函式產生索引條目。

在版本 0.4 中新增。

:no-index-entry:

不要為記錄的函式產生索引條目。與 :no-index: 不同，交叉參照仍然會建立。

在版本 8.2 中新增。

自動記錄屬性或資料的文件

.. autodata::
.. autoattribute::

記錄模組層級變數或常數（「資料」）或類別屬性的文件。預設情況下，此指令僅插入變數本身的 docstring

.. autodata:: noodles.FLOUR_TYPE

將產生如下的來源

.. py:data:: noodles.FLOUR_TYPE

   The FLOUR_TYPE constant's docstring.

此指令也可以包含其自身的內容，這些內容將在 docstring 之後插入到產生的非自動指令來源中。

因此，您也可以混合自動和非自動成員文件，如下所示

.. autodata:: noodles.FLOUR_TYPE

   .. hint:: Cooking time can vary by which flour type is used.

版本 0.6 變更：autodata 和 autoattribute 現在可以擷取 docstring。

版本 1.1 變更：現在允許在指派的同一行中使用 Doc-comment。

選項

:no-index:

不要為記錄的變數或常數產生索引條目。

在版本 0.4 中新增。

:no-index-entry:

不要為記錄的變數或常數產生索引條目。與 :no-index: 不同，交叉參照仍然會建立。

在版本 8.2 中新增。

:annotation: value （字串）

在版本 1.2 中新增。

預設情況下，autodoc 會嘗試透過內省取得變數的類型註解和值，並在變數名稱後顯示它。若要覆寫此行為，可以使用變數值的自訂字串作為 annotation 的參數。

例如，如果 FILE_MODE 的執行階段值為 0o755，則顯示的值將為 493（因為 oct(493) == '0o755'）。這可以透過設定 :annotation: = 0o755 來修正。

如果 :annotation: 在沒有參數的情況下使用，則不會顯示變數的值或類型提示。

:no-value:

版本 3.4 新增。

若要顯示變數的類型提示而不顯示值，請使用 :no-value: 選項。如果同時使用 :annotation: 和 :no-value: 選項，則 :no-value: 無效。

設定

您還可以設定組態值

autoclass_content
類型:
str
預設:
'class'

此值選擇要插入到 autoclass 指令主體中的內容。可能的值為

'class'

'class'

僅插入類別的 docstring。您仍然可以使用 automethod 或 autoclass 的 members 選項，將 __init__ 文件記錄為個別方法。

'both'

類別和 __init__ 方法的 docstring 都會串連並插入。

'init'

版本 0.3 新增。

僅插入 __init__ 方法的 docstring。

如果類別沒有 __init__ 方法，或者 __init__ 方法的 docstring 為空，但類別具有 __new__ 方法的 docstring，則會改用 __new__ 方法的 docstring。

版本 1.4 新增。
類型:
str
預設:
autodoc_class_signature

'mixed'

autodoc_class_signature

此值選擇如何顯示由 autoclass 指令定義的類別簽名。可能的值為

'mixed'

顯示帶有類別名稱的簽名。

版本 4.1 新增。

'separated'
類型:
str
預設:
將簽名顯示為方法。

autodoc_member_order

  • 'alphabetical'

  • 定義 automodule 和 autoclass 成員的列出順序。支援的值為

    • 'alphabetical'：使用字母順序。

    • 'groupwise'：依成員類型排序。順序為

      適用於模組、例外、類別、函式、資料

    適用於類別：類別方法、靜態方法、方法，

  • 以及屬性/特性

在版本 0.6 中新增。

成員在群組內依字母順序排序。

'bysource'：使用成員在原始碼中出現的順序。這需要模組必須是具有可用原始碼的 Python 模組。
類型:
版本 1.0 變更：支援 'bysource'。
預設:
{}

autodoc_default_options

autodoc_default_options = {
    'members': 'var1, var2',
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

dict[str, str | bool]

autodoc 指令的預設選項。它們會自動套用於所有 autodoc 指令。它必須是一個字典，將選項名稱對應到值。例如

'no-index'：請參閱 automodule:no-index。

'no-index-entry'：請參閱 automodule:no-index-entry。

版本 1.8 新增。

版本 2.0 變更：接受 True 作為值。

版本 2.1 變更：新增 'imported-members'。

版本 4.1 變更：新增 'class-doc-from'。
類型:
版本 4.5 變更：新增 'no-value'。
預設:
autodoc_docstring_signature

bool

True

從 C 模組匯入的函式無法內省，因此無法自動判斷此類函式的簽名。但是，通常使用的慣例是將簽名放在函式的 docstring 的第一行。

在版本 1.1 中新增。

如果此布林值設定為 True（預設值），autodoc 將查看函式和方法的 docstring 的第一行，如果它看起來像簽名，則將該行用作簽名並從 docstring 內容中移除。

autodoc 將繼續尋找多個簽名行，並在第一個看起來不像簽名的行停止。這對於宣告多載函式簽名很有用。

版本 3.1 變更：支援多載簽名
類型:
版本 4.0 變更：多載簽名不需要以反斜線分隔
預設:
[]

autodoc_mock_imports

autodoc_mock_imports = ['django']

list[str]

此值包含要模擬的模組列表。當某些外部相依性在建置時未滿足並中斷建置程序時，這非常有用。您可能只需指定相依性本身的根套件，並省略子模組

將模擬 django 套件下的所有匯入。

版本 1.3 新增。
類型:
str
預設:
版本 1.6 變更：此組態值僅需要宣告應模擬的頂層模組。

autodoc_typehints

  • 'signature'

  • 此值控制如何表示類型提示。此設定接受下列值

  • 'signature' – 在簽名中顯示類型提示

  • 'description' – 以函式或方法的內容顯示類型提示。多載函式或方法的類型提示仍將在簽名中表示。

'none' – 不顯示類型提示

'both' – 在簽名中以及函式或方法的內容中顯示類型提示

多載函式或方法將不會在描述中包含類型提示，因為無法將所有可能的多載準確地表示為參數列表。

版本 2.1 新增。

版本 3.0 新增：新增 'description' 選項。
類型:
str
預設:
版本 4.1 新增：新增 'both' 選項。

autodoc_typehints_description_target

  • 'all'

  • 此值控制當 autodoc_typehints 設定為 'description' 時，是否記錄未記錄參數和傳回值的類型。支援的值

  • 'all'：無論是否已記錄，都會記錄所有參數和傳回值的類型。

'documented'：類型僅會針對 docstring 已記錄的參數或傳回值進行記錄。

'documented_params'：僅當參數記錄在 docstring 中時，才會註解參數類型。傳回類型始終會被註解（除非它是 None）。

版本 4.0 新增。
類型:
版本 5.0 新增：新增 'documented_params' 選項。
預設:
{}

autodoc_type_aliases

dict[str, str]

使用者定義 類型別名的字典，將類型名稱對應到完整限定的物件名稱。它用於使類型別名在文件中保持未評估狀態。

from __future__ import annotations

AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

def f() -> AliasType:
    ...

類型別名僅在您的程式透過 延後評估註解 (PEP 563) 功能啟用 from __future__ import annotations 時才可用。

.. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

   ...

例如，有程式碼使用類型別名

.. py:function:: f() -> your.module.AliasType:

   ...

如果未設定 autodoc_type_aliases，autodoc 將由此程式碼產生內部標記，如下所示

如果您將 autodoc_type_aliases 設定為 {'AliasType': 'your.module.AliasType'}，它會在內部產生以下文件
類型:
str
預設:
版本 3.3 新增。

autodoc_typehints_format

  • 'short'

  • 此值控制類型提示的格式。此設定接受下列值

'fully-qualified' – 顯示模組名稱及其類型提示的名稱

'short' – 隱藏類型提示的前導模組名稱（例如 io.StringIO -> StringIO）

版本 4.4 新增。
類型:
版本 4.5 變更：新增 'no-value'。
預設:
版本 5.0 變更：預設設定已變更為 'short'

autodoc_preserve_defaults

False

如果為 True，則在產生文件時，函式的預設引數值將不會被評估。它會將它們保留在原始碼中。
類型:
版本 4.5 變更：新增 'no-value'。
預設:
autodoc_docstring_signature

版本 4.0 新增：作為實驗性功能新增。這將在未來整合到 autodoc 核心中。

autodoc_use_type_comments

如果為 True，則嘗試從原始碼讀取 # type: ... 註解，以補充遺失的類型註解。

如果您的原始碼未使用類型註解，則可以停用此功能，例如，如果它專門使用類型註解或未使用任何類型的類型提示。
類型:
版本 4.5 變更：新增 'no-value'。
預設:
autodoc_docstring_signature

版本 8.2 新增：新增選項以透過新的 autodoc_use_type_comments 選項停用類型註解的使用，預設值為 True 以實現向後相容性。預設值將在 Sphinx 10 中變更為 False。

autodoc_warningiserror

此值控制在匯入模組期間 sphinx-build --fail-on-warning 的行為。如果給定 False，則當匯入的模組發出警告時，autodoc 會強制抑制錯誤。
類型:
版本 4.5 變更：新增 'no-value'。
預設:
autodoc_docstring_signature

版本 8.1 變更：此選項現在無效，因為 --fail-on-warning 不再提早結束。

在版本 1.7 中新增。

autodoc_inherit_docstrings
類型:
此值控制 docstring 繼承。如果設定為 True，則類別或方法的 docstring（如果未明確設定）會從父類別繼承。
預設:
()

suppress_warnings

  • Sequence[str]

  • autodoc 透過 suppress_warnings 支援抑制警告訊息。它定義了以下額外的警告類型

autodoc

autodoc.import_object

Docstring 預處理

在版本 0.4 中新增。

autodoc 提供以下額外事件

autodoc-process-docstring(app, what, name, obj, options, lines)

  • 當 autodoc 讀取並處理 docstring 時發出。lines 是字串列表 – 處理過的 docstring 的行 – 事件處理常式可以就地修改這些行，以變更 Sphinx 放入輸出的內容。

  • 參數:

  • app – Sphinx 應用程式物件

  • what – docstring 所屬物件的類型（'module'、'class'、'exception'、'function'、'method'、'attribute' 之一）

  • options – 指令的選項：一個具有屬性的物件，包含 inherited_members、undoc_members、show_inheritance 和 no-index 屬性。如果 auto 指令給定了同名的旗標選項，則這些屬性為 true

  • lines – 文件字串的行，請參閱上方

autodoc-before-process-signature(app, obj, bound_method)

在版本 2.4 中加入。

在 autodoc 格式化物件的簽名之前發出。事件處理器可以修改物件以變更其簽名。

autodoc-process-docstring(app, what, name, obj, options, lines)

  • 當 autodoc 讀取並處理 docstring 時發出。lines 是字串列表 – 處理過的 docstring 的行 – 事件處理常式可以就地修改這些行，以變更 Sphinx 放入輸出的內容。

  • what – docstring 所屬物件的類型（'module'、'class'、'exception'、'function'、'method'、'attribute' 之一）

  • bound_method – 一個布林值，指示物件是否為綁定方法

autodoc-process-signature(app, what, name, obj, options, signature, return_annotation)

在版本 0.5 中新增。

當 autodoc 格式化物件的簽名後發出。事件處理器可以回傳一個新的元組 (signature, return_annotation)，以變更 Sphinx 放入輸出的內容。

autodoc-process-docstring(app, what, name, obj, options, lines)

  • 當 autodoc 讀取並處理 docstring 時發出。lines 是字串列表 – 處理過的 docstring 的行 – 事件處理常式可以就地修改這些行，以變更 Sphinx 放入輸出的內容。

  • 參數:

  • app – Sphinx 應用程式物件

  • what – docstring 所屬物件的類型（'module'、'class'、'exception'、'function'、'method'、'attribute' 之一）

  • options – 指令的選項：一個具有屬性的物件，包含 inherited_members、undoc_members、show_inheritance 和 no-index 屬性。如果 auto 指令給定了同名的旗標選項，則這些屬性為 true

  • signature – 函式簽名，形式為字串 '(parameter_1, parameter_2)'，如果內省失敗且指令中未指定簽名，則為 None。

  • return_annotation – 函式回傳註釋，形式為字串 ' -> annotation'，如果沒有回傳註釋，則為 None。

sphinx.ext.autodoc 模組為事件 autodoc-process-docstring 中常用的文件字串處理提供工廠函式

sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: Sequence[str] | None = None) → _AutodocProcessDocstringListener[原始碼]

回傳一個監聽器，該監聽器會移除每個文件字串的開頭 pre 行和結尾 post 行。如果 what 是一個字串序列，則只會處理 what 中類型的文件字串。

像這樣使用（例如在 conf.py 檔案的 setup() 函式中）

from sphinx.ext.autodoc import cut_lines

app.connect('autodoc-process-docstring', cut_lines(4, what={'module'}))

這可以（並且應該）用來取代 automodule_skip_lines。

sphinx.ext.autodoc.between(marker: str, what: Sequence[str] | None = None, keepempty: bool = False, exclude: bool = False) → _AutodocProcessDocstringListener[原始碼]

回傳一個監聽器，該監聽器會保留或排除（如果 exclude 為 True）符合 marker 正則表達式的行之間的行。如果沒有行符合，則產生的文件字串將為空，因此除非 keepempty 為 true，否則不會進行任何變更。

如果 what 是一個字串序列，則只會處理 what 中類型的文件字串。

autodoc-process-bases(app, name, obj, options, bases)

當 autodoc 讀取並處理類別以確定基底類別時發出。bases 是類別列表，事件處理器可以**就地**修改該列表，以變更 Sphinx 放入輸出的內容。僅當給定 show-inheritance 選項時才會發出。

autodoc-process-docstring(app, what, name, obj, options, lines)

  • 當 autodoc 讀取並處理 docstring 時發出。lines 是字串列表 – 處理過的 docstring 的行 – 事件處理常式可以就地修改這些行，以變更 Sphinx 放入輸出的內容。

  • app – Sphinx 應用程式物件

  • what – docstring 所屬物件的類型（'module'、'class'、'exception'、'function'、'method'、'attribute' 之一）

  • options – 給定給類別指令的選項

  • bases – 基底類別簽名的列表。請參閱上方。

版本 4.1 新增。

在 4.3 版本中變更: bases 可以包含作為基底類別名稱的字串。它將被視為 reStructuredText 處理。

略過成員

autodoc 允許使用者定義一個自訂方法，以使用以下事件來決定是否應將成員包含在文件中

autodoc-skip-member(app, what, name, obj, skip, options)

在版本 0.5 中新增。

當 autodoc 必須決定是否應將成員包含在文件中時發出。如果處理器回傳 True，則會排除該成員。如果處理器回傳 False，則會包含該成員。

如果多個已啟用的擴充功能處理 autodoc-skip-member 事件，autodoc 將使用處理器回傳的第一個非 None 值。處理器應回傳 None 以退回到 autodoc 和其他已啟用的擴充功能的略過行為。

autodoc-process-docstring(app, what, name, obj, options, lines)

  • 當 autodoc 讀取並處理 docstring 時發出。lines 是字串列表 – 處理過的 docstring 的行 – 事件處理常式可以就地修改這些行，以變更 Sphinx 放入輸出的內容。

  • 參數:

  • app – Sphinx 應用程式物件

  • what – docstring 所屬物件的類型（'module'、'class'、'exception'、'function'、'method'、'attribute' 之一）

  • skip – 一個布林值，指示如果使用者處理器未覆寫決策，autodoc 是否將略過此成員

  • options – 指令的選項：一個具有屬性的物件，包含 inherited_members、undoc_members、show_inheritance 和 no-index 屬性。如果 auto 指令給定了同名的旗標選項，則這些屬性為 true