-M buildername

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

مهم:

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

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

نکته:

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

-b buildername, --builder buildername

یک سازنده را انتخاب می‌کند.

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

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

-a, --write-all

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

نکته:

تغییر یافته در نسخهٔ 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.

در نسخه 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 اضافه شد.

MAKE

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

PAPER

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

نکته:

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.

• PYTHONWARNINGS= make html (در Linux/Mac)
• export PYTHONWARNINGS= و سپس اجرای make html (در Linux/Mac)
• set PYTHONWARNINGS= و سپس اجرای make html (در Windows)
• ویرایش Makefile/make.bat خود و تنظیم این متغیر محیطی