.\" Man page generated from reStructuredText .\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "SPHINX-BUILD" "1" "Mar 04, 2026" "9.1.0" "Sphinx" .SH "نام (NAME)" sphinx-build \- ابزار تولید مستندات Sphinx .SH "خلاصه دستور (SYNOPSIS)" .sp \fBsphinx\-build\fP [\fIoptions\fP] <\fIsourcedir\fP> <\fIoutputdir\fP> [\fIfilenames\fP ...] .SH "توضیحات (DESCRIPTION)" .sp دستور \fBsphinx\-build\fP مستندات را از فایل‌های موجود در \fB\fP تولید کرده و در \fB\fP قرار می‌دهد\&. .sp \fBsphinx\-build\fP برای تنظیمات پیکربندی به‌دنبال \fB/conf.py\fP می‌گردد\&. می‌توان از \fBsphinx\-quickstart(1)\fP برای تولید فایل‌های الگو، از جمله \fBconf.py\fP استفاده کرد\&. .sp \fBsphinx\-build\fP می‌تواند مستندات را در قالب‌های متفاوتی ایجاد کند\&. یک قالب با مشخص کردن نام سازنده (builder) در خط فرمان انتخاب می‌شود؛ حالت پیش‌فرض آن HTML است\&. سازنده‌ها همچنین می‌توانند وظایف دیگری مرتبط با پردازش مستندات را انجام دهند\&. برای فهرستی از سازنده‌های موجود، به Builders \%<> مراجعه کنید\&. .sp به‌طور پیش‌فرض، هر آنچه که قدیمی یا تغییریافته باشد ساخته می‌شود\&. خروجی فقط برای فایل‌های انتخاب‌شده را می‌توان با مشخص کردن نام تک‌تک فایل‌ها ساخت\&. .SH "گزینه‌ها (OPTIONS)" .INDENT 0.0 .TP .B \-M buildername یک سازنده را با استفاده از \fImake\-mode\fP انتخاب می‌کند\&. برای فهرستی از تمامی سازنده‌های داخلی Sphinx به Builders \%<> مراجعه کنید\&. افزونه‌ها می‌توانند سازنده‌های خود را اضافه کنند\&. .sp \fBمهم:\fP .INDENT 7.0 .INDENT 3.5 ابزار Sphinx گزینهٔ \fB\-M\fP را تنها در صورتی تشخیص می‌دهد که در ابتدا، همراه با پوشه‌های مبدأ و خروجی، پیش از هر گزینهٔ دیگری قرار گیرد\&. برای مثال: .INDENT 0.0 .INDENT 3.5 .sp .EX sphinx\-build \-M html ./source ./build \-\-fail\-on\-warning .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp حالت \fImake\-mode\fP عملکرد ساخت مشابهی با یک Makefile یا Make.bat پیش‌فرض فراهم می‌کند، و خط‌لوله‌های ساخت اضافی زیر را ارائه می‌دهد: .INDENT 7.0 .TP .B \fIlatexpdf\fP فایل‌های LaTeX را می‌سازد و آن‌ها را از طریق \fBpdflatex\fP، یا مطابق با تنظیمات \fBlatex_engine\fP \%<#\:confval-latex_engine> اجرا می‌کند\&. اگر \fBlanguage\fP \%<#\:confval-language> بر روی \fB\(aqja\(aq\fP تنظیم شده باشد، به‌طور خودکار از خط‌لولهٔ تبدیل LaTeX به PDF ابزار \fBplatex/dvipdfmx\fP استفاده خواهد شد\&. .TP .B \fIinfo\fP فایل‌های Texinfo را می‌سازد و آن‌ها را از طریق \fBmakeinfo\fP اجرا می‌کند\&. .TP .B \fIhelp\fP فهرستی از اهداف سازندهٔ معتبر را در خروجی چاپ کرده و خارج می‌شود\&. .UNINDENT .sp \fBنکته:\fP .INDENT 7.0 .INDENT 3.5 مکان‌های پیش‌فرض پوشهٔ خروجی هنگام استفاده از \fImake\-mode\fP با حالت‌های پیش‌فرض هنگام استفاده از \fB\-b\fP متفاوت است\&. .INDENT 0.0 .IP \(bu 2 درخت‌های مستند (doctrees) در \fB/doctrees\fP ذخیره می‌شوند .IP \(bu 2 فایل‌های خروجی در \fB/\fP ذخیره می‌شوند .UNINDENT .UNINDENT .UNINDENT .sp در نسخهٔ 1.2.1 اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-b buildername, \-\-builder buildername یک سازنده را انتخاب می‌کند\&. .sp برای فهرستی از تمامی سازنده‌های داخلی Sphinx به Builders \%<> مراجعه کنید\&. افزونه‌ها می‌توانند سازنده‌های خود را اضافه کنند\&. .sp تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند \fB\-\-builder\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-a, \-\-write\-all در صورت مشخص شدن، همیشه تمام فایل‌های خروجی را می‌نویسد\&. حالت پیش‌فرض، نوشتن فایل‌های خروجی تنها برای فایل‌های مبدأ جدید و تغییریافته است\&. (این موضوع ممکن است شامل همهٔ سازنده‌ها نشود\&.) .sp \fBنکته:\fP .INDENT 7.0 .INDENT 3.5 این گزینه فایل‌های مبدأ را دوباره نمی‌خواند\&. برای خواندن و پردازش مجدد هر فایل، به جای آن از \fB\-\-fresh\-env\fP استفاده کنید\&. .UNINDENT .UNINDENT .sp تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند \fB\-\-write\-all\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-E, \-\-fresh\-env از یک محیط ذخیره‌شده \%<#\:term-environment> (ساختاری که تمام ارجاعات متقابل را کَش می‌کند) استفاده نمی‌کند، بلکه آن را کاملاً بازسازی می‌نماید\&. حالت پیش‌فرض تنها خواندن و تجزیهٔ فایل‌های مبدئی است که از آخرین اجرا جدید بوده یا تغییر کرده‌اند\&. .sp تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند \fB\-\-fresh\-env\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-t tag, \-\-tag tag برچسب \fItag\fP را تعریف می‌کند\&. این گزینه مربوط به دستورالعمل‌های \fBonly\fP \%<#\:directive-only> است که محتوای خود را تنها در صورت تنظیم بودن برچسب‌های خاص شامل می‌کنند\&. برای جزئیات بیشتر به بخش گنجاندن محتوا بر اساس برچسب‌ها \%<#\:tags> مراجعه کنید\&. .sp در نسخهٔ 0.6 اضافه شد. .sp تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند \fB\-\-tag\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-d path, \-\-doctree\-dir path از آن‌جا که Sphinx پیش از نوشتن فایل خروجی باید تمامی فایل‌های مبدأ را بخواند و تجزیه کند، فایل‌های مبدأ تجزیه‌شده به‌صورت \(dqdoctree pickles\(dq کَش می‌شوند\&. به‌طور معمول، این فایل‌ها در پوشه‌ای به نام \fB\&.doctrees\fP در زیر پوشهٔ ساخت قرار می‌گیرند؛ با این گزینه می‌توانید یک پوشهٔ کَش دیگر را انتخاب کنید (doctreeها می‌توانند بین همهٔ سازنده‌ها به اشتراک گذاشته شوند)\&. .sp تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند \fB\-\-doctree\-dir\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-j N, \-\-jobs N فرایند ساخت را به‌صورت موازی روی \fIN\fP پردازه توزیع می‌کند تا ساخت روی دستگاه‌های چندپردازنده‌ای کارآمدتر شود\&. این ویژگی تنها در سیستم‌هایی کار می‌کند که از \(dqfork\(dq پشتیبانی می‌کنند؛ Windows پشتیبانی نمی‌شود\&. توجه داشته باشید که همهٔ بخش‌ها و همهٔ سازنده‌های Sphinx را نمی‌توان موازی‌سازی کرد\&. اگر آرگومان \fBauto\fP داده شود، Sphinx از تعداد پردازنده‌ها (CPUها) به‌عنوان \fIN\fP استفاده می‌کند\&. پیش‌فرض 1 است\&. .sp در نسخهٔ 1.2 اضافه شد: این گزینه باید \fIآزمایشی (experimental)\fP در نظر گرفته شود\&. .sp تغییر یافته در نسخهٔ 1.7: پشتیبانی از آرگومان \fBauto\fP\&. .sp تغییر یافته در نسخهٔ 6.2: افزودن گزینهٔ بلند \fB\-\-jobs\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-c path, \-\-conf\-dir path به‌دنبال \fBconf.py\fP در پوشهٔ مبدأ نمی‌گردد، بلکه در عوض از پوشهٔ پیکربندی داده‌شده استفاده می‌کند\&. توجه داشته باشید انتظار می‌رود فایل‌ها و مسیرهای گوناگون دیگری که توسط مقادیر پیکربندی تعیین شده‌اند نسبت به پوشهٔ پیکربندی نسبی باشند، بنابراین باید در این مکان نیز حضور داشته باشند\&. .sp در نسخهٔ 0.3 اضافه شد. .sp تغییر یافته در نسخهٔ 7.3: افزودن گزینهٔ بلند \fB\-\-conf\-dir\fP\&. .UNINDENT .INDENT 0.0.TP .B \-C, \-\-isolated به دنبال فایل پیکربندی نگرد؛ گزینه‌ها را فقط از طریق گزینه \fB\-\-define\fP دریافت کن. .sp در نسخه 0.5 اضافه شد. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-isolated\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-D setting=value, \-\-define setting=value بازنویسی مقدار پیکربندی تنظیم‌شده در فایل \fBconf.py\fP. مقدار باید یک عدد، رشته، لیست یا مقدار دیکشنری باشد. .sp برای لیست‌ها، می‌توانید عناصر را مانند این با ویرگول جدا کنید: \fB\-D html_theme_path=path1,path2\fP\&. .sp برای مقادیر دیکشنری، نام تنظیم و کلید را مانند این وارد کنید: \fB\-D latex_elements.docclass=scrartcl\fP\&. .sp برای مقادیر بولی، از \fB0\fP یا \fB1\fP به عنوان مقدار استفاده کنید. .sp در نسخه 0.6 تغییر کرد: مقدار اکنون می‌تواند یک مقدار دیکشنری باشد. .sp در نسخه 1.3 تغییر کرد: مقدار اکنون می‌تواند یک مقدار لیست نیز باشد. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-define\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-A name=value, \-\-html\-define name=value اختصاص \fIvalue\fP به \fIname\fP در قالب‌های HTML. .sp در نسخه 0.5 اضافه شد. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-html\-define\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-n, \-\-nitpicky اجرا در حالت سخت‌گیرانه (nitpicky). در حال حاضر، این حالت برای تمام ارجاع‌های مفقود هشدار ایجاد می‌کند. برای روشی جهت مستثنی کردن برخی ارجاع‌ها به عنوان \(dqشناخته‌شده به عنوان مفقود\(dq، مقدار پیکربندی \fBnitpick_ignore\fP \%<#\:confval-nitpick_ignore> را ببینید. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-nitpicky\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-N, \-\-no\-color عدم تولید خروجی رنگی. .sp در نسخه 1.6 تغییر کرد: گزینه طولانی \fB\-\-no\-color\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-\-color تولید خروجی رنگی. به صورت پیش‌فرض به طور خودکار تشخیص داده می‌شود. .sp در نسخه 1.6 اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-v, \-\-verbose افزایش پرگویی (سطح لاگ). این گزینه می‌تواند تا سه بار برای دریافت خروجی بیشتر لاگ‌های اشکال‌زدایی داده شود. این گزینه مستلزم \fB\-T\fP است. .sp در نسخه 1.2 اضافه شد. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-verbose\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-q, \-\-quiet هیچ چیزی در خروجی استاندارد نوشته نشود، تنها هشدارها و خطاها در خطای استاندارد نوشته شوند. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-quiet\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-Q, \-\-silent هیچ چیزی در خروجی استاندارد نوشته نشود، همچنین از نمایش هشدارها جلوگیری شود. تنها خطاها در خطای استاندارد نوشته می‌شوند. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-silent\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-w file, \-\-warning\-file file نوشتن هشدارها (و خطاها) در فایل داده‌شده، علاوه بر خطای استاندارد. .sp در نسخه 7.3 تغییر کرد: دنباله‌های کنترلی ANSI هنگام نوشتن در \fIfile\fP حذف می‌شوند. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-warning\-file\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-W, \-\-fail\-on\-warning تبدیل هشدارها به خطا. این بدان معناست که در صورت ایجاد هرگونه هشدار در طول ساخت، \fBsphinx\-build\fP با وضعیت خروج 1 خارج می‌شود. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-fail\-on\-warning\fP اضافه شد. .sp در نسخه 8.1 تغییر کرد: \fBsphinx\-build\fP دیگر با اولین هشدار خارج نمی‌شود، بلکه در عوض کل فرآیند ساخت را اجرا می‌کند و در صورتی که هرگونه هشداری ایجاد شده باشد با وضعیت خروج 1 خارج می‌شود. این رفتار پیش‌تر با \fB\-\-keep\-going\fP فعال می‌شد. .UNINDENT .INDENT 0.0 .TP .B \-\-keep\-going از نسخه Sphinx 8.1، گزینه \fB\-\-keep\-going\fP همیشه فعال است. پیش‌تر، تنها هنگام استفاده از \fB\-\-fail\-on\-warning\fP قابل اعمال بود، که به طور پیش‌فرض \fBsphinx\-build\fP را با اولین هشدار خارج می‌کرد. استفاده از \fB\-\-keep\-going\fP باعث اجرای \fBsphinx\-build\fP تا مرحله تکمیل می‌شود و در صورت مواجهه با خطا با وضعیت خروج 1 خارج می‌گردد. .sp در نسخه 1.8 اضافه شد. .sp در نسخه 8.1 تغییر کرد: \fBsphinx\-build\fP دیگر با اولین هشدار خارج نمی‌شود، به این معنی که در عمل \fB\-\-keep\-going\fP همیشه فعال است. این گزینه برای حفظ سازگاری نگه‌داشته شده است، اما ممکن است در آینده حذف شود. .UNINDENT .INDENT 0.0 .TP .B \-T, \-\-show\-traceback نمایش کامل traceback هنگام رخ دادن یک استثنای مدیریت‌نشده. در غیر این صورت، تنها یک خلاصه نمایش داده می‌شود و اطلاعات traceback برای تحلیل بیشتر در یک فایل ذخیره می‌گردد. .sp در نسخه 1.2 اضافه شد. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-show\-traceback\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-P, \-\-pdb (تنها برای اشکال‌زدایی مفید است.) در صورت رخ دادن یک استثنای مدیریت‌نشده حین ساخت، اشکال‌زدای پایتون \fBpdb\fP \% را اجرا کن. .sp در نسخه 7.3 تغییر کرد: گزینه طولانی \fB\-\-pdb\fP اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-\-exception\-on\-warning ایجاد یک استثنا هنگامی که در حین ساخت هشداری صادر می‌شود. این می‌تواند در ترکیب با \fB\-\-pdb\fP برای اشکال‌زدایی هشدارها مفید باشد. .sp در نسخه 8.1 اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help, \-\-version نمایش خلاصه کاربرد یا نسخه Sphinx. .sp در نسخه 1.2 اضافه شد. .UNINDENT .sp شما همچنین می‌توانید پس از دایرکتوری‌های مبدا و ساخت، یک یا چند نام فایل را در خط فرمان مشخص کنید. سپس Sphinx تلاش خواهد کرد تا فقط این فایل‌های خروجی (و وابستگی‌های آن‌ها) را بسازد..SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)" .sp دستور \fBsphinx\-build\fP به متغیرهای محیطی زیر مراجعه می‌کند: .INDENT 0.0 .TP .B MAKE مسیری به دستور make. استفاده از نام دستور نیز مجاز است. \fBsphinx\-build\fP از آن برای فراخوانی فرایند ساخت فرعی در حالت make\-mode استفاده می‌کند. .UNINDENT .sp گزینه‌های Makefile .sp فایل‌های \fBMakefile\fP و \fBmake.bat\fP ایجاد شده توسط \fBsphinx\-quickstart\fP معمولاً \fBsphinx\-build\fP را تنها با گزینه‌های \fB\-b\fP و \fB\-d\fP اجرا می‌کنند. با این حال، آن‌ها از متغیرهای زیر برای سفارشی‌سازی رفتار پشتیبانی می‌کنند: .INDENT 0.0 .TP .B PAPER این متغیر کلید \fB\(aqpapersize\(aq\fP از \fBlatex_elements\fP \%<#\:confval-latex_elements> را تنظیم می‌کند: یعنی \fBPAPER=a4\fP آن را روی \fB\(aqa4paper\(aq\fP و \fBPAPER=letter\fP آن را روی \fB\(aqletterpaper\(aq\fP تنظیم می‌کند\&. .sp \fBنکته:\fP .INDENT 7.0 .INDENT 3.5 استفاده از این متغیر محیطی در Sphinx 1.5 دچار اشکال شد، زیرا \fBa4\fP یا \fBletter\fP به جای مقادیر مورد نیاز \fBa4paper\fP و به‌ترتیب \fBletterpaper\fP به عنوان گزینه به سند LaTeX ارسال می‌شدند\&. این مشکل در نسخهٔ 1.7.7 رفع شد. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B SPHINXBUILD دستوری که باید به جای \fBsphinx\-build\fP استفاده شود\&. .UNINDENT .INDENT 0.0 .TP .B BUILDDIR دایرکتوری ساختی که باید به جای دایرکتوری انتخاب‌شده در \fBsphinx\-quickstart\fP استفاده شود\&. .UNINDENT .INDENT 0.0 .TP .B SPHINXOPTS گزینه‌های اضافی برای \fBsphinx\-build\fP\&. این گزینه‌ها را می‌توان از طریق متغیر میان‌بر \fBO\fP (حرف بزرگ \(aqo\(aq) نیز تنظیم کرد. .UNINDENT .INDENT 0.0 .TP .B NO_COLOR در صورت تنظیم (صرف‌نظر از مقدار آن)، \fBsphinx\-build\fP از رنگ در خروجی ترمینال استفاده نخواهد کرد. \fBNO_COLOR\fP بر \fBFORCE_COLOR\fP تقدم دارد\&. برای مشاهدهٔ سایر کتابخانه‌هایی که از این استاندارد جامعه پشتیبانی می‌کنند، no\-color.org \% را ببینید. .sp افزوده‌شده در نسخهٔ 4.5.0. .UNINDENT .INDENT 0.0 .TP .B FORCE_COLOR در صورت تنظیم (صرف‌نظر از مقدار آن)، \fBsphinx\-build\fP از رنگ در خروجی ترمینال استفاده خواهد کرد. \fBNO_COLOR\fP بر \fBFORCE_COLOR\fP تقدم دارد\&. .sp افزوده‌شده در نسخهٔ 4.5.0. .UNINDENT .SH "هشدارهای منسوخ‌شدن (DEPRECATION WARNINGS)" .sp اگر هنگام ساخت سند کاربر، هرگونه هشدار منسوخ‌شدن مانند \fBRemovedInSphinxXXXWarning\fP نمایش داده شود، یکی از افزونه‌های Sphinx در حال استفاده از قابلیت‌های منسوخ‌شده است. در این حالت، لطفاً آن را به نویسندهٔ افزونه گزارش دهید. .sp برای غیرفعال کردن هشدارهای منسوخ‌شدن، لطفاً متغیر محیطی \fBPYTHONWARNINGS=\fP را در محیط خود تنظیم کنید. برای مثال: .INDENT 0.0 .IP \(bu 2 \fBPYTHONWARNINGS= make html\fP (در Linux/Mac) .IP \(bu 2 \fBexport PYTHONWARNINGS=\fP و سپس اجرای \fBmake html\fP (در Linux/Mac) .IP \(bu 2 \fBset PYTHONWARNINGS=\fP و سپس اجرای \fBmake html\fP (در Windows) .IP \(bu 2 ویرایش Makefile/make.bat خود و تنظیم این متغیر محیطی .UNINDENT .SH "همچنین ببینید (SEE ALSO)" .sp \fBsphinx\-quickstart(1)\fP .SH "کپی‌رایت و تکثیر (COPYRIGHT)" 2007-2026، توسعه‌دهندگان Sphinx .\" End of generated man page.