sphinx.ext.apidoc – 從 Python 套件產生 API 文件

在版本 8.2 中新增。

sphinx.ext.apidoc 是一個從 Python 套件自動產生 Sphinx 原始碼的工具。它提供 sphinx-apidoc 命令列工具作為擴充功能，使其可以在 Sphinx 建置過程中執行。

此擴充功能將產生的原始碼檔案寫入提供的目錄，然後 Sphinx 使用 sphinx.ext.autodoc 擴充功能讀取這些檔案。

警告

sphinx.ext.apidoc 產生使用 sphinx.ext.autodoc 來記錄所有找到模組的原始碼檔案。如果任何模組在匯入時有副作用，當執行 sphinx-build 時，這些副作用將被 autodoc 執行。

如果您要記錄腳本（而不是函式庫模組），請確保它們的主要例程受到 if __name__ == '__main__' 條件的保護。

設定

apidoc 擴充功能使用以下設定值

apidoc_modules
類型:
Sequence[dict[str, str | int | bool | Sequence[str] | Set[str]]
預設值:
()

描述要記錄模組的字典列表或序列。如果任何字典中的值未指定，則通用設定值將用作預設值。

例如

apidoc_modules = [
    {'path': 'path/to/module', 'destination': 'source/'},
    {
        'path': 'path/to/another_module',
        'destination': 'source/',
        'exclude_patterns': ['**/test*'],
        'max_depth': 4,
        'follow_links': False,
        'separate_modules': False,
        'include_private': False,
        'no_headings': False,
        'module_first': False,
        'implicit_namespaces': False,
        'automodule_options': {
            'members', 'show-inheritance', 'undoc-members'
        },
    },
]

有效的鍵為

'path'

要記錄的模組路徑 (必要)。這必須是絕對路徑或相對於設定目錄的路徑。

'destination'

產生檔案的輸出目錄 (必要)。這必須是相對於來源目錄的路徑，如果不存在將會建立。

'exclude_patterns'

請參閱 apidoc_exclude_patterns。

'max_depth'

請參閱 apidoc_max_depth。

'follow_links'

請參閱 apidoc_follow_links。

'separate_modules'

請參閱 apidoc_separate_modules。

'include_private'

請參閱 apidoc_include_private。

'no_headings'

請參閱 apidoc_no_headings。

'module_first'

請參閱 apidoc_module_first。

'implicit_namespaces'

請參閱 apidoc_implicit_namespaces。

'automodule_options'

請參閱 apidoc_automodule_options。

apidoc_exclude_patterns
類型:
Sequence[str]
預設值:
()

要排除在產生之外的模式序列。這些可以是文字路徑或 fnmatch 風格的模式。

apidoc_max_depth
類型:
int
預設值:
4

要在產生的目錄中顯示的子模組最大深度。

類型:
bool
預設值:
False

追蹤符號連結。

apidoc_separate_modules
類型:
bool
預設值:
False

將每個模組的文件放在個別頁面上。

apidoc_include_private
類型:
bool
預設值:
False

為帶有前導底線的 '_private' 模組產生文件。

apidoc_no_headings
類型:
bool
預設值:
False

不要為模組/套件建立標題。當原始碼 docstring 已經包含標題時很有用。

apidoc_module_first
類型:
bool
預設值:
False

將模組文件放在子模組文件之前。

apidoc_implicit_namespaces
類型:
bool
預設值:
False

預設情況下，sphinx-apidoc 僅處理 sys.path 搜尋模組。Python 3.3 引入了 PEP 420 隱式命名空間，允許模組路徑結構，例如 foo/bar/module.py 或 foo/bar/baz/__init__.py (請注意 bar 和 foo 是命名空間，而不是模組)。

使用 PEP 420 隱式命名空間解譯模組路徑。

apidoc_automodule_options
類型:
Set[str]
預設值:
{'members', 'show-inheritance', 'undoc-members'}

要傳遞給產生的 automodule 指令的選項。