SPHINX-BUILD(1)                     Sphinx                     SPHINX-BUILD(1)

نام (NAME)
       sphinx-build - ابزار تولید مستندات Sphinx

خلاصه دستور (SYNOPSIS)
       sphinx-build [options] <sourcedir> <outputdir> [filenames ...]

توضیحات (DESCRIPTION)
       دستور sphinx-build مستندات را از فایل‌های موجود در <sourcedir> تولید
       کرده و در <outputdir> قرار می‌دهد.

       sphinx-build برای تنظیمات پیکربندی به‌دنبال <sourcedir>/conf.py می‌گردد.
       می‌توان از sphinx-quickstart(1) برای تولید فایل‌های الگو، از جمله conf.py
       استفاده کرد.

       sphinx-build می‌تواند مستندات را در قالب‌های متفاوتی ایجاد کند.  یک قالب
       با مشخص کردن نام سازنده (builder) در خط فرمان انتخاب می‌شود؛ حالت پیش‌فرض
       آن HTML است. سازنده‌ها همچنین می‌توانند وظایف دیگری مرتبط با پردازش
       مستندات را انجام دهند. برای فهرستی از سازنده‌های موجود، به Builders <>
       مراجعه کنید.

       به‌طور پیش‌فرض، هر آنچه که قدیمی یا تغییریافته باشد ساخته می‌شود. خروجی
       فقط برای فایل‌های انتخاب‌شده را می‌توان با مشخص کردن نام تک‌تک فایل‌ها ساخت.

گزینه‌ها (OPTIONS)

       -M buildername
              یک سازنده را با استفاده از make-mode انتخاب می‌کند.  برای فهرستی
              از تمامی سازنده‌های داخلی Sphinx به Builders <> مراجعه کنید.
              افزونه‌ها می‌توانند سازنده‌های خود را اضافه کنند.

              مهم:
                 ابزار Sphinx گزینهٔ -M را تنها در صورتی تشخیص می‌دهد که در
                 ابتدا، همراه با پوشه‌های مبدأ و خروجی، پیش از هر گزینهٔ دیگری
                 قرار گیرد.  برای مثال:

                    sphinx-build -M html ./source ./build --fail-on-warning

              حالت make-mode عملکرد ساخت مشابهی با یک Makefile یا Make.bat
              پیش‌فرض فراهم می‌کند، و خط‌لوله‌های ساخت اضافی زیر را ارائه می‌دهد:

              latexpdf
                     فایل‌های LaTeX را می‌سازد و آن‌ها را از طریق pdflatex، یا
                     مطابق با تنظیمات latex_engine <#confval-latex_engine>
                     اجرا می‌کند.  اگر language <#confval-language> بر روی 'ja'
                     تنظیم شده باشد، به‌طور خودکار از خط‌لولهٔ تبدیل LaTeX به PDF
                     ابزار platex/dvipdfmx استفاده خواهد شد.

              info   فایل‌های Texinfo را می‌سازد و آن‌ها را از طریق makeinfo اجرا
                     می‌کند.

              help   فهرستی از اهداف سازندهٔ معتبر را در خروجی چاپ کرده و خارج
                     می‌شود.

              نکته:
                 مکان‌های پیش‌فرض پوشهٔ خروجی هنگام استفاده از make-mode با
                 حالت‌های پیش‌فرض هنگام استفاده از -b متفاوت است.

                 • درخت‌های مستند (doctrees) در <outputdir>/doctrees ذخیره
                   می‌شوند

                 • فایل‌های خروجی در <outputdir>/<builder name> ذخیره می‌شوند

              در نسخهٔ 1.2.1 اضافه شد.


       -b buildername, --builder buildername
              یک سازنده را انتخاب می‌کند.

              برای فهرستی از تمامی سازنده‌های داخلی Sphinx به Builders <>
              مراجعه کنید.  افزونه‌ها می‌توانند سازنده‌های خود را اضافه کنند.

              تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند --builder.


       -a, --write-all
              در صورت مشخص شدن، همیشه تمام فایل‌های خروجی را می‌نویسد. حالت
              پیش‌فرض، نوشتن فایل‌های خروجی تنها برای فایل‌های مبدأ جدید و
              تغییریافته است. (این موضوع ممکن است شامل همهٔ سازنده‌ها نشود.)

              نکته:
                 این گزینه فایل‌های مبدأ را دوباره نمی‌خواند.  برای خواندن و
                 پردازش مجدد هر فایل، به جای آن از --fresh-env استفاده کنید.

              تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند --write-all.


       -E, --fresh-env
              از یک محیط ذخیره‌شده <#term-environment> (ساختاری که تمام ارجاعات
              متقابل را کَش می‌کند) استفاده نمی‌کند، بلکه آن را کاملاً بازسازی
              می‌نماید. حالت پیش‌فرض تنها خواندن و تجزیهٔ فایل‌های مبدئی است که از
              آخرین اجرا جدید بوده یا تغییر کرده‌اند.

              تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند --fresh-env.


       -t tag, --tag tag
              برچسب tag را تعریف می‌کند.  این گزینه مربوط به دستورالعمل‌های only
              <#directive-only> است که محتوای خود را تنها در صورت تنظیم بودن
              برچسب‌های خاص شامل می‌کنند.  برای جزئیات بیشتر به بخش گنجاندن
              محتوا بر اساس برچسب‌ها <#tags> مراجعه کنید.

              در نسخهٔ 0.6 اضافه شد.


              تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند --tag.


       -d path, --doctree-dir path
              از آن‌جا که Sphinx پیش از نوشتن فایل خروجی باید تمامی فایل‌های
              مبدأ را بخواند و تجزیه کند، فایل‌های مبدأ تجزیه‌شده به‌صورت
              "doctree pickles" کَش می‌شوند.  به‌طور معمول، این فایل‌ها در پوشه‌ای
              به نام .doctrees در زیر پوشهٔ ساخت قرار می‌گیرند؛ با این گزینه
              می‌توانید یک پوشهٔ کَش دیگر را انتخاب کنید (doctreeها می‌توانند بین
              همهٔ سازنده‌ها به اشتراک گذاشته شوند).

              تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند --doctree-dir.


       -j N, --jobs N
              فرایند ساخت را به‌صورت موازی روی N پردازه توزیع می‌کند تا ساخت روی
              دستگاه‌های چندپردازنده‌ای کارآمدتر شود.  این ویژگی تنها در
              سیستم‌هایی کار می‌کند که از "fork" پشتیبانی می‌کنند؛ Windows
              پشتیبانی نمی‌شود.  توجه داشته باشید که همهٔ بخش‌ها و همهٔ سازنده‌های
              Sphinx را نمی‌توان موازی‌سازی کرد.  اگر آرگومان auto داده شود،
              Sphinx از تعداد پردازنده‌ها (CPUها) به‌عنوان N استفاده می‌کند.
              پیش‌فرض 1 است.

              در نسخهٔ 1.2 اضافه شد: این گزینه باید آزمایشی (experimental) در
              نظر گرفته شود.


              تغییر یافته در نسخهٔ 1.7: پشتیبانی از آرگومان auto.


              تغییر یافته در نسخهٔ 6.2: افزودن گزینهٔ بلند --jobs.


       -c path, --conf-dir path
              به‌دنبال conf.py در پوشهٔ مبدأ نمی‌گردد، بلکه در عوض از پوشهٔ
              پیکربندی داده‌شده استفاده می‌کند. توجه داشته باشید انتظار می‌رود
              فایل‌ها و مسیرهای گوناگون دیگری که توسط مقادیر پیکربندی تعیین
              شده‌اند نسبت به پوشهٔ پیکربندی نسبی باشند، بنابراین باید در این
              مکان نیز حضور داشته باشند.

              در نسخهٔ 0.3 اضافه شد.


              تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند --conf-dir.

       -C, --isolated به دنبال فایل پیکربندی نگرد؛ گزینه‌ها را فقط از طریق
       گزینه --define دریافت کن.

       در نسخه 0.5 اضافه شد.


       در نسخه 7.3 تغییر کرد: گزینه طولانی --isolated اضافه شد.


       -D setting=value, --define setting=value
              بازنویسی مقدار پیکربندی تنظیم‌شده در فایل conf.py. مقدار باید یک
              عدد، رشته، لیست یا مقدار دیکشنری باشد.

              برای لیست‌ها، می‌توانید عناصر را مانند این با ویرگول جدا کنید: -D
              html_theme_path=path1,path2.

              برای مقادیر دیکشنری، نام تنظیم و کلید را مانند این وارد کنید: -D
              latex_elements.docclass=scrartcl.

              برای مقادیر بولی، از 0 یا 1 به عنوان مقدار استفاده کنید.

              در نسخه 0.6 تغییر کرد: مقدار اکنون می‌تواند یک مقدار دیکشنری
              باشد.


              در نسخه 1.3 تغییر کرد: مقدار اکنون می‌تواند یک مقدار لیست نیز
              باشد.


              در نسخه 7.3 تغییر کرد: گزینه طولانی --define اضافه شد.


       -A name=value, --html-define name=value
              اختصاص value به name در قالب‌های HTML.

              در نسخه 0.5 اضافه شد.


              در نسخه 7.3 تغییر کرد: گزینه طولانی --html-define اضافه شد.


       -n, --nitpicky
              اجرا در حالت سخت‌گیرانه (nitpicky). در حال حاضر، این حالت برای
              تمام ارجاع‌های مفقود هشدار ایجاد می‌کند. برای روشی جهت مستثنی کردن
              برخی ارجاع‌ها به عنوان "شناخته‌شده به عنوان مفقود"، مقدار پیکربندی
              nitpick_ignore <#confval-nitpick_ignore> را ببینید.

              در نسخه 7.3 تغییر کرد: گزینه طولانی --nitpicky اضافه شد.


       -N, --no-color
              عدم تولید خروجی رنگی.

              در نسخه 1.6 تغییر کرد: گزینه طولانی --no-color اضافه شد.


       --color
              تولید خروجی رنگی. به صورت پیش‌فرض به طور خودکار تشخیص داده می‌شود.

              در نسخه 1.6 اضافه شد.


       -v, --verbose
              افزایش پرگویی (سطح لاگ). این گزینه می‌تواند تا سه بار برای دریافت
              خروجی بیشتر لاگ‌های اشکال‌زدایی داده شود. این گزینه مستلزم -T است.

              در نسخه 1.2 اضافه شد.


              در نسخه 7.3 تغییر کرد: گزینه طولانی --verbose اضافه شد.


       -q, --quiet
              هیچ چیزی در خروجی استاندارد نوشته نشود، تنها هشدارها و خطاها در
              خطای استاندارد نوشته شوند.

              در نسخه 7.3 تغییر کرد: گزینه طولانی --quiet اضافه شد.


       -Q, --silent
              هیچ چیزی در خروجی استاندارد نوشته نشود، همچنین از نمایش هشدارها
              جلوگیری شود. تنها خطاها در خطای استاندارد نوشته می‌شوند.

              در نسخه 7.3 تغییر کرد: گزینه طولانی --silent اضافه شد.


       -w file, --warning-file file
              نوشتن هشدارها (و خطاها) در فایل داده‌شده، علاوه بر خطای
              استاندارد.

              در نسخه 7.3 تغییر کرد: دنباله‌های کنترلی ANSI هنگام نوشتن در file
              حذف می‌شوند.


              در نسخه 7.3 تغییر کرد: گزینه طولانی --warning-file اضافه شد.


       -W, --fail-on-warning
              تبدیل هشدارها به خطا.  این بدان معناست که در صورت ایجاد هرگونه
              هشدار در طول ساخت، sphinx-build با وضعیت خروج 1 خارج می‌شود.

              در نسخه 7.3 تغییر کرد: گزینه طولانی --fail-on-warning اضافه شد.


              در نسخه 8.1 تغییر کرد: sphinx-build دیگر با اولین هشدار خارج
              نمی‌شود، بلکه در عوض کل فرآیند ساخت را اجرا می‌کند و در صورتی که
              هرگونه هشداری ایجاد شده باشد با وضعیت خروج 1 خارج می‌شود.  این
              رفتار پیش‌تر با --keep-going فعال می‌شد.


       --keep-going
              از نسخه Sphinx 8.1، گزینه --keep-going همیشه فعال است.  پیش‌تر،
              تنها هنگام استفاده از --fail-on-warning قابل اعمال بود، که به
              طور پیش‌فرض sphinx-build را با اولین هشدار خارج می‌کرد.  استفاده
              از --keep-going باعث اجرای sphinx-build تا مرحله تکمیل می‌شود و
              در صورت مواجهه با خطا با وضعیت خروج 1 خارج می‌گردد.

              در نسخه 1.8 اضافه شد.


              در نسخه 8.1 تغییر کرد: sphinx-build دیگر با اولین هشدار خارج
              نمی‌شود، به این معنی که در عمل --keep-going همیشه فعال است.  این
              گزینه برای حفظ سازگاری نگه‌داشته شده است، اما ممکن است در آینده
              حذف شود.


       -T, --show-traceback
              نمایش کامل traceback هنگام رخ دادن یک استثنای مدیریت‌نشده. در غیر
              این صورت، تنها یک خلاصه نمایش داده می‌شود و اطلاعات traceback
              برای تحلیل بیشتر در یک فایل ذخیره می‌گردد.

              در نسخه 1.2 اضافه شد.


              در نسخه 7.3 تغییر کرد: گزینه طولانی --show-traceback اضافه شد.


       -P, --pdb
              (تنها برای اشکال‌زدایی مفید است.) در صورت رخ دادن یک استثنای
              مدیریت‌نشده حین ساخت، اشکال‌زدای پایتون pdb
              <https://docs.python.org/3/library/pdb.html#module-pdb> را اجرا
              کن.

              در نسخه 7.3 تغییر کرد: گزینه طولانی --pdb اضافه شد.


       --exception-on-warning
              ایجاد یک استثنا هنگامی که در حین ساخت هشداری صادر می‌شود.  این
              می‌تواند در ترکیب با --pdb برای اشکال‌زدایی هشدارها مفید باشد.

              در نسخه 8.1 اضافه شد.


       -h, --help, --version
              نمایش خلاصه کاربرد یا نسخه Sphinx.

              در نسخه 1.2 اضافه شد.


       شما همچنین می‌توانید پس از دایرکتوری‌های مبدا و ساخت، یک یا چند نام فایل
       را در خط فرمان مشخص کنید. سپس Sphinx تلاش خواهد کرد تا فقط این فایل‌های
       خروجی (و وابستگی‌های آن‌ها) را بسازد..SH "متغیرهای محیطی (ENVIRONMENT
       VARIABLES)"

       دستور sphinx-build به متغیرهای محیطی زیر مراجعه می‌کند:

       MAKE   مسیری به دستور make. استفاده از نام دستور نیز مجاز است.
              sphinx-build از آن برای فراخوانی فرایند ساخت فرعی در حالت
              make-mode استفاده می‌کند.

       گزینه‌های Makefile

       فایل‌های Makefile و make.bat ایجاد شده توسط sphinx-quickstart معمولاً
       sphinx-build را تنها با گزینه‌های -b و -d اجرا می‌کنند. با این حال، آن‌ها
       از متغیرهای زیر برای سفارشی‌سازی رفتار پشتیبانی می‌کنند:

       PAPER  این متغیر کلید 'papersize' از latex_elements <#confval-
              latex_elements> را تنظیم می‌کند: یعنی PAPER=a4 آن را روی
              'a4paper' و PAPER=letter آن را روی 'letterpaper' تنظیم می‌کند.

              نکته:
                 استفاده از این متغیر محیطی در Sphinx 1.5 دچار اشکال شد، زیرا
                 a4 یا letter به جای مقادیر مورد نیاز a4paper و به‌ترتیب
                 letterpaper به عنوان گزینه به سند LaTeX ارسال می‌شدند. این
                 مشکل در نسخهٔ 1.7.7 رفع شد.

       SPHINXBUILD
              دستوری که باید به جای sphinx-build استفاده شود.

       BUILDDIR
              دایرکتوری ساختی که باید به جای دایرکتوری انتخاب‌شده در
              sphinx-quickstart استفاده شود.

       SPHINXOPTS
              گزینه‌های اضافی برای sphinx-build. این گزینه‌ها را می‌توان از طریق
              متغیر میان‌بر O (حرف بزرگ 'o') نیز تنظیم کرد.

       NO_COLOR
              در صورت تنظیم (صرف‌نظر از مقدار آن)، sphinx-build از رنگ در خروجی
              ترمینال استفاده نخواهد کرد. NO_COLOR بر FORCE_COLOR تقدم دارد.
              برای مشاهدهٔ سایر کتابخانه‌هایی که از این استاندارد جامعه پشتیبانی
              می‌کنند، no-color.org <https://no-color.org> را ببینید.

              افزوده‌شده در نسخهٔ 4.5.0.


       FORCE_COLOR
              در صورت تنظیم (صرف‌نظر از مقدار آن)، sphinx-build از رنگ در خروجی
              ترمینال استفاده خواهد کرد. NO_COLOR بر FORCE_COLOR تقدم دارد.

              افزوده‌شده در نسخهٔ 4.5.0.


هشدارهای منسوخ‌شدن (DEPRECATION WARNINGS)
       اگر هنگام ساخت سند کاربر، هرگونه هشدار منسوخ‌شدن مانند
       RemovedInSphinxXXXWarning نمایش داده شود، یکی از افزونه‌های Sphinx در
       حال استفاده از قابلیت‌های منسوخ‌شده است. در این حالت، لطفاً آن را به
       نویسندهٔ افزونه گزارش دهید.

       برای غیرفعال کردن هشدارهای منسوخ‌شدن، لطفاً متغیر محیطی PYTHONWARNINGS=
       را در محیط خود تنظیم کنید. برای مثال:

       • PYTHONWARNINGS= make html (در Linux/Mac)

       • export PYTHONWARNINGS= و سپس اجرای make html (در Linux/Mac)

       • set PYTHONWARNINGS= و سپس اجرای make html (در Windows)

       • ویرایش Makefile/make.bat خود و تنظیم این متغیر محیطی

همچنین ببینید (SEE ALSO)
       sphinx-quickstart(1)

کپی‌رایت و تکثیر (COPYRIGHT)
       2007-2026، توسعه‌دهندگان Sphinx

9.1.0                            March 4, 2026                 SPHINX-BUILD(1)