sphinx-apidoc

概要

sphinx-apidoc [選項] -o <輸出路徑> <模組路徑> [排除模式 …]

描述

sphinx-apidoc 是一個用於自動產生 Sphinx 原始碼的工具，它使用 autodoc 擴充功能，以其他自動 API 文件工具的風格，記錄整個套件。

模組路徑 是要記錄的 Python 套件路徑，而 輸出路徑 是產生來源檔案放置的目錄。任何給定的 排除模式 都是 fnmatch 風格 的檔案和/或目錄模式，將從產生中排除。

警告

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

如果您要記錄腳本（與程式庫模組相對），請確保它們的主常式受到 if __name__ == '__main__' 條件的保護。

選項

-o <輸出路徑>

放置輸出檔案的目錄。如果它不存在，則會建立它。

-q

不要在標準輸出上輸出任何內容，僅將警告和錯誤寫入標準錯誤。

-f, --force

強制覆寫任何現有的產生檔案。

-l, --follow-links

追蹤符號連結。預設為 False。

-n, --dry-run

不建立或移除任何檔案。

-s <suffix>

產生來源檔案的後綴。預設為 rst。

-d <MAXDEPTH>

產生目錄檔案的最大深度。預設為 4。

--tocfile

目錄檔案的檔名。預設為 modules。

-T, --no-toc

不建立目錄檔案。當提供 --full 時會被忽略。

--remove-old

移除輸出目錄中不再建立的現有檔案。與 --full 不相容。

-F, --full

使用與 sphinx-quickstart 相同的機制產生完整的 Sphinx 專案 (conf.py, Makefile 等)。

-e, --separate

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

版本 1.2 新增。

-E, --no-headings

不為模組/套件建立標題。例如，當 docstring 已經包含標題時，這很有用。

-P, --private

包含 “_private” 模組。

版本 1.2 新增。

--implicit-namespaces

如果沒有此選項，sphinx-apidoc 會在 sys.path 中搜尋包含 __init__.py 檔案或單一檔案 Python 模組的 Python 套件。

此選項改為使用 PEP 420 隱式命名空間，允許諸如 foo/bar/module.py 或 foo/bar/baz/__init__.py 的佈局路徑 (請注意，bar 和 foo 是命名空間，而不是模組)。

-M, --module-first

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

當指定 --full 時，會使用這些選項

-a

將 module_path 附加到 sys.path。

-H <專案>

設定要放入產生檔案中的專案名稱 (請參閱 project)。

-A <作者>

設定要放入產生檔案中的作者姓名 (請參閱 copyright)。

-V <版本>

設定要放入產生檔案中的專案版本 (請參閱 version)。

-R <發行版本>

設定要放入產生檔案中的專案發行版本 (請參閱 release)。

專案範本

版本 2.2 新增：sphinx-apidoc 的專案範本選項

-t, --templatedir=TEMPLATEDIR

範本檔案的範本目錄。您可以修改 apidoc 產生的 sphinx 專案檔案的範本。允許使用以下 Jinja2 範本檔案

  • module.rst.jinja

  • package.rst.jinja

  • toc.rst.jinja

  • root_doc.rst.jinja

  • conf.py.jinja

  • Makefile.jinja

  • Makefile.new.jinja

  • make.bat.jinja

  • make.bat.new.jinja

詳細資訊，請參考 Sphinx 提供的系統範本檔案。( sphinx/templates/apidoc 和 sphinx/templates/quickstart )

環境

SPHINX_APIDOC_OPTIONS

要附加到產生的 automodule 指令的逗號分隔選項列表。預設為 members,undoc-members,show-inheritance。

參見

sphinx-build(1), sphinx-autogen(1)