نام (NAME)

sphinx-apidoc - ابزار تولید خودکار مستندات API برای اسفینکس

خلاصه دستور (SYNOPSIS)

sphinx-apidoc [گزینه‌ها] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN ...]

توضیحات (DESCRIPTION)

دستور sphinx-apidoc ابزاری برای تولید خودکار فایل‌های منبع اسفینکس (Sphinx) است که با استفاده از افزونهٔ autodoc <#module-sphinx.ext.autodoc> یک بستهٔ کامل را به شیوهٔ سایر ابزارهای مستندسازی خودکار API مستند می‌کند.

مقدار MODULE_PATH مسیر بستهٔ پایتونی است که باید مستند شود، و OUTPUT_PATH دایرکتوری محل قرارگیری فایل‌های منبع تولیدشده است. هرگونه EXCLUDE_PATTERN مشخص‌شده، الگوهای فایل و/یا دایرکتوری به سبک fnmatch https://docs.python.org/3/library/fnmatch.html هستند که از فرآیند تولید مستثنی خواهند شد.

هشدار:

دستور sphinx-apidoc فایل‌های منبعی تولید می‌کند که از sphinx.ext.autodoc <#module-sphinx.ext.autodoc> برای مستندسازی تمامی ماژول‌های یافت‌شده استفاده می‌کنند. اگر ماژولی هنگام وارد کردن (import) دارای اثرات جانبی (side effects) باشد، این اثرات در زمان اجرای sphinx-build توسط autodoc اجرا خواهند شد.

اگر در حال مستندسازی اسکریپت‌ها هستید (در مقایسه با ماژول‌های کتابخانه‌ای)، اطمینان حاصل کنید که روال اصلی آن‌ها توسط شرط if __name__ == '__main__' محافظت شده باشد.

گزینه‌ها (OPTIONS)

-o <OUTPUT_PATH>: دایرکتوری برای قرار دادن فایل‌های خروجی. اگر وجود نداشته باشد، ایجاد می‌شود.

-q: هیچ پیامی در خروجی استاندارد چاپ نمی‌کند؛ فقط هشدارها و خطاها را در خطای استاندارد می‌نویسد.

-f, --force: بازنویسی اجباری هرگونه فایل تولیدشدهٔ موجود.

-l, --follow-links: پیوندهای نمادین (symbolic links) را دنبال می‌کند. مقدار پیش‌فرض: False.

-n, --dry-run: هیچ فایلی را ایجاد یا حذف نمی‌کند.

-s <suffix>: پسوند فایل‌های منبع تولیدشده. مقدار پیش‌فرض: rst.

-d <MAXDEPTH>: حداکثر عمق برای فایل فهرست مطالب (table of contents) تولیدشده. مقدار پیش‌فرض: 4.

--tocfile: نام فایل برای فهرست مطالب. مقدار پیش‌فرض: modules.

-T, --no-toc: فایل فهرست مطالب ایجاد نمی‌کند. در صورت مشخص شدن --full نادیده گرفته می‌شود.

--remove-old: فایل‌های موجود در دایرکتوری خروجی را که دیگر تولید نمی‌شوند حذف می‌کند. با --full سازگار نیست.

-F, --full: یک پروژهٔ کامل اسفینکس (conf.py، Makefile و غیره) را با استفاده از مکانیزمی مشابه sphinx-quickstart تولید می‌کند.

-e, --separate: مستندات هر ماژول را در صفحهٔ جداگانهٔ خودش قرار می‌دهد.
اضافه‌شده در نسخهٔ 1.2.

-E, --no-headings: برای ماژول‌ها/بسته‌ها عنوان (heading) ایجاد نمی‌کند. این گزینه برای مواقعی که docstringها از قبل حاوی عنوان هستند، مفید است.

-P, --private: ماژول‌های خصوصی ("_private") را نیز شامل می‌کند.
اضافه‌شده در نسخهٔ 1.2.

--implicit-namespaces: بدون این گزینه، sphinx-apidoc مسیرهای sys.path https://docs.python.org/3/library/sys.html#sys.path را برای بسته‌های پایتون حاوی فایل‌های __init__.py یا ماژول‌های تک‌فایلی پایتون جستجو می‌کند.
در عوض، این گزینه از فضاهای نام ضمنی (implicit namespaces) مربوط به PEP 420 https://peps.python.org/pep-0420 استفاده می‌کند که ساختارهای مسیری مانند foo/bar/module.py یا foo/bar/baz/__init__.py را مجاز می‌سازد (توجه داشته باشید که foo و bar فضای نام هستند، نه ماژول).

-M, --module-first: مستندات ماژول را قبل از مستندات زیرماژول قرار می‌دهد.

این گزینه‌ها زمانی که --full مشخص شده باشد استفاده می‌شوند:

-a: مسیر module_path را به sys.path اضافه می‌کند.

-H <project>: نام پروژه را برای درج در فایل‌های تولیدشده تنظیم می‌کند (ببینید: project <#confval-project>).

-A <author>: نام نویسنده(ها) را برای درج در فایل‌های تولیدشده تنظیم می‌کند (ببینید: copyright <#confval-copyright>).

-V <version>: نسخهٔ پروژه را برای درج در فایل‌های تولیدشده تنظیم می‌کند (ببینید: version <#confval-version>).

-R <release>: شماره انتشار (release) پروژه را برای درج در فایل‌های تولیدشده تنظیم می‌کند (ببینید: release <#confval-release>).

قالب‌بندی پروژه (Project templating)

اضافه‌شده در نسخهٔ 2.2: گزینه‌های قالب‌بندی پروژه برای sphinx-apidoc

-t, --templatedir=TEMPLATEDIR: دایرکتوری الگوها برای فایل‌های قالب. شما می‌توانید قالب‌های فایل‌های پروژهٔ اسفینکس تولیدشده توسط apidoc را تغییر دهید. فایل‌های قالب 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)

محیط (ENVIRONMENT)

SPHINX_APIDOC_OPTIONS: فهرستی جداشده با کاما از گزینه‌ها برای اضافه شدن به دستورالعمل‌های automodule تولیدشده. مقدار پیش‌فرض: members,undoc-members,show-inheritance.

همچنین ببینید (SEE ALSO)

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

حق نشر (COPYRIGHT)

2007-2026, the Sphinx developers

March 4, 2026

9.1.0