SPHINX-APIDOC(1)                    Sphinx                    SPHINX-APIDOC(1)

نام (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

9.1.0                            March 4, 2026                SPHINX-APIDOC(1)