'\" t
.TH "CARGO\-DOC" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "نام (NAME)"
cargo\-doc \- ساخت مستندات یک بسته
.SH "خلاصه دستور (SYNOPSIS)"
\fBcargo doc\fR [\fIگزینه‌ها\fR]
.SH "توضیحات (DESCRIPTION)"
مستندات بستهٔ محلی و تمام وابستگی‌ها را می‌سازد. خروجی در \fBtarget/doc\fR با قالب معمول rustdoc قرار می‌گیرد.
.sp
\fBنکته:\fR تولید مستندات به‌صورت تجمعی است: فایل‌های مستندات موجود در دایرکتوری هدف در میان فراخوانی‌های مختلف \fBcargo doc\fR حفظ می‌شوند. برای حذف مستندات تولیدشدهٔ پیشین، گزینهٔ \fB\-\-doc\fR را به \fBcargo\-clean\fR(1) بدهید.
.SH "گزینه‌ها (OPTIONS)"
.SS "گزینه‌های مستندسازی (Documentation Options)"
.sp
\fB\-\-open\fR
.RS 4
باز کردن مستندات در یک مرورگر پس از ساخت آن‌ها. این دستور از مرورگر پیش‌فرض شما استفاده خواهد کرد مگر اینکه مرورگر دیگری را در متغیر محیطی \fBBROWSER\fR مشخص کرده باشید یا از گزینهٔ پیکربندی \fI\f(BIdoc.browser\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docbrowser> استفاده کنید.
.RE
.sp
\fB\-\-no\-deps\fR
.RS 4
برای وابستگی‌ها مستندات نساز.
.RE
.sp
\fB\-\-document\-private\-items\fR
.RS 4
گنجاندن موارد غیرعمومی در مستندات. در صورت مستندسازی یک هدف باینری (binary target)، این حالت به‌طور پیش‌فرض فعال خواهد بود.
.RE
.SS "انتخاب بسته (Package Selection)"
به‌طور پیش‌فرض، هنگامی که هیچ گزینه‌ای برای انتخاب بسته داده نشده باشد، بسته‌های انتخاب‌شده به فایل مانیفستِ انتخاب‌شده بستگی دارند (بر پایهٔ دایرکتوری کاری جاری، در صورتی که \fB\-\-manifest\-path\fR داده نشده باشد). اگر مانیفست، ریشهٔ یک فضای کاری (workspace) باشد، اعضای پیش‌فرض فضای کاری انتخاب می‌شوند، در غیر این صورت تنها بسته‌ای که توسط مانیفست تعریف شده است انتخاب خواهد شد.
.sp
اعضای پیش‌فرض یک فضای کاری را می‌توان به‌طور صریح با کلید \fBworkspace.default\-members\fR در مانیفست ریشه مشخص کرد. در صورت عدم تنظیم، یک فضای کاری مجازی شامل همهٔ اعضای فضای کاری خواهد بود (معادل ارسال \fB\-\-workspace\fR)، و یک فضای کاری غیرمجازی فقط شامل خودِ کریت (crate) ریشه خواهد بود.
.sp
\fB\-p\fR \fIspec\fR\[u2026], 
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
فقط بسته‌های مشخص‌شده را مستندسازی کن. برای قالب SPEC به \fBcargo\-pkgid\fR(1) مراجعه کنید. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس مانند \fB*\fR، \fB?\fR و \fB[]\fR\& پشتیبانی می‌کند. با این وجود، برای جلوگیری از بسط تصادفی الگوهای glob توسط شل پیش از پردازش آن‌ها توسط Cargo، باید در دو طرف هر الگو از علامت‌های نقل‌قول تکی یا جفتی استفاده کنید.
.RE
.sp
\fB\-\-workspace\fR
.RS 4
مستندسازی تمام اعضا در فضای کاری.
.RE
.sp
\fB\-\-all\fR
.RS 4
نام مستعار منسوخ‌شده برای \fB\-\-workspace\fR\&.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
مستثنی کردن بسته‌های مشخص‌شده. باید در کنار پرچم \fB\-\-workspace\fR استفاده شود. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس مانند \fB*\fR، \fB?\fR و \fB[]\fR\& پشتیبانی می‌کند. با این حال، برای جلوگیری از بسط تصادفی الگوهای glob توسط شل پیش از پردازش آن‌ها توسط Cargo، باید در دو طرف هر الگو از علامت‌های نقل‌قول تکی یا جفتی استفاده کنید.
.RE
.SS "انتخاب هدف (Target Selection)"
هنگامی که گزینه‌ای برای انتخاب هدف داده نشود، \fBcargo doc\fR تمام اهداف باینری و کتابخانه‌ایِ بستهٔ انتخاب‌شده را مستندسازی خواهد کرد. اگر نام هدف باینری با هدف کتابخانه (lib) یکسان باشد، از باینری صرف‌نظر می‌شود. باینری‌هایی که ویژگی‌های الزامی (\fBrequired\-features\fR) ناموجود داشته باشند نیز نادیده گرفته می‌شوند.
.sp
رفتار پیش‌فرض را می‌توان با تنظیم \fBdoc = false\fR برای هدف در تنظیمات مانیفست تغییر داد. استفاده از گزینه‌های انتخاب هدف، پرچم \fBdoc\fR را نادیده می‌گیرد و همواره هدف داده‌شده را مستندسازی می‌کند.
.sp
\fB\-\-lib\fR
.RS 4
مستندسازی کتابخانهٔ بسته.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
مستندسازی باینری مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس پشتیبانی می‌کند.
.RE
.sp
\fB\-\-bins\fR
.RS 4
مستندسازی تمام اهداف باینری.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
مستندسازی نمونهٔ (example) مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس پشتیبانی می‌کند.
.RE
.sp
\fB\-\-examples\fR
.RS 4
مستندسازی تمام اهداف نمونه (examples).
.RE.SS "انتخاب ویژگی‌ها (Feature Selection)"
پرچم‌های ویژگی به شما اجازه می‌دهند تعیین کنید کدام ویژگی‌ها فعال شوند. زمانی که هیچ گزینهٔ ویژگی مشخص نشده باشد، ویژگی \fBdefault\fR برای هر بستهٔ انتخاب‌شده فعال می‌شود.
.sp
برای جزئیات بیشتر، \fIمستندات ویژگی‌ها\fR را در <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
ببینید.
.sp
\fB\-F\fR \fIfeatures\fR, 
\fB\-\-features\fR \fIfeatures\fR
.RS 4
فهرستی از ویژگی‌ها جداشده با فاصله یا کاما جهت فعال‌سازی. ویژگی‌های اعضای فضای کاری را می‌توان با نحو \fBpackage\-name/feature\-name\fR فعال کرد. این پرچم می‌تواند چندین بار مشخص شود که تمام ویژگی‌های تعیین‌شده را فعال می‌کند.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
فعال‌سازی تمام ویژگی‌های موجود در تمامی بسته‌های انتخاب‌شده.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
ویژگی \fBdefault\fR بسته‌های انتخاب‌شده را فعال نمی‌کند.
.RE
.SS "گزینه‌های کامپایل (Compilation Options)"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
تولید مستندات برای معماری هدف مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود. مقدار پیش‌فرض، معماری میزبان است. قالب کلی این سه‌تایی (triple) به‌صورت
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\& است.
.sp
مقادیر ممکن:
.sp
.RS 4
\h'-04'\(bu\h'+03'هر هدف پشتیبانی‌شده در \fBrustc \-\-print target\-list\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fB"host\-tuple"\fR، که در درون برنامه با هدفِ میزبان جایگزین خواهد شد. این گزینه به‌ویژه زمانی کاربرد دارد که در حال کامپایل متقابل (cross\-compilation) برخی کریت‌ها هستید و نمی‌خواهید ماشین میزبان خود را به‌طور صریح به‌عنوان یک هدف مشخص کنید (برای نمونه، یک \fBxtask\fR در پروژه‌ای مشترک که ممکن است توسط چندین میزبان روی آن کار شود).
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'مسیری به مشخصات یک هدف سفارشی. برای اطلاعات بیشتر، \fICustom Target Lookup Path\fR را در <https://doc.rust\-lang.org/rustc/targets/custom.html#custom\-target\-lookup\-path> ببینید.
.RE
.sp
این مورد را می‌توان با \fIمقدار پیکربندی\fR \fBbuild.target\fR در <https://doc.rust\-lang.org/cargo/reference/config.html>\& نیز تعیین کرد.
.sp
توجه داشته باشید که مشخص کردن این پرچم باعث می‌شود Cargo در حالت متفاوتی اجرا شود که در آن مصنوعات هدف در یک دایرکتوری جداگانه قرار می‌گیرند. برای جزئیات بیشتر، مستندات \fIحافظه پنهان ساخت (build cache)\fR را در <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> ببینید.
.RE
.sp
\fB\-r\fR, 
\fB\-\-release\fR
.RS 4
تولید مستندات برای مصنوعات بهینه‌سازی‌شده با نمایهٔ \fBrelease\fR.
همچنین گزینهٔ \fB\-\-profile\fR را برای انتخاب یک نمایهٔ خاص بر اساس نام آن ببینید.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
تولید مستندات با نمایهٔ داده‌شده.
برای جزئیات بیشتر دربارهٔ نمایه‌ها، \fIمرجع\fR را در <https://doc.rust\-lang.org/cargo/reference/profiles.html> ببینید.
.RE
.sp
\fB\-\-timings\fR
.RS 4
اطلاعاتی دربارهٔ مدت‌زمان هر کامپایل خروجی می‌دهد و داده‌های همزمانی را در طول زمان رهگیری می‌کند.
.sp
در پایان فرایند ساخت، یک فایل \fBcargo\-timing.html\fR در دایرکتوری \fBtarget/cargo\-timings\fR
نوشته خواهد شد. در صورتی که بخواهید یک اجرای پیشین را بررسی کنید، گزارش دیگری نیز با یک برچسب زمانی در نام فایل ذخیره می‌شود.
این گزارش‌ها تنها برای خوانش انسانی مناسب هستند و داده‌های زمان‌بندیِ ماشین‌خوان ارائه نمی‌دهند.
.RE
.SS "گزینه‌های خروجی (Output Options)"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
دایرکتوری برای تمامی مصنوعات و فایل‌های واسط تولیدشده. همچنین می‌تواند با متغیر محیطی \fBCARGO_TARGET_DIR\fR یا \fIمقدار پیکربندی\fR \fBbuild.target\-dir\fR در <https://doc.rust\-lang.org/cargo/reference/config.html>\& تعیین شود.
مقدار پیش‌فرض \fBtarget\fR در ریشهٔ فضای کاری است.
.RE.SS "گزینه‌های نمایش (Display Options)"
.sp
\fB\-v\fR, 
\fB\-\-verbose\fR
.RS 4
استفاده از خروجی پرجزئیات. می‌تواند دو بار برای خروجی \[lq]بسیار پرجزئیات\[rq] مشخص شود که شامل خروجی‌های اضافی مانند هشدارهای وابستگی و خروجی اسکریپت ساخت است.
همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.verbose\fR در <https://doc.rust\-lang.org/cargo/reference/config.html> تعیین شود\&.
.RE
.sp
\fB\-q\fR, 
\fB\-\-quiet\fR
.RS 4
پیام‌های لاگ Cargo چاپ نشوند.
همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.quiet\fR در <https://doc.rust\-lang.org/cargo/reference/config.html> تعیین شود\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
کنترل زمان استفاده از خروجی رنگی. مقادیر معتبر:
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBauto\fR (پیش‌فرض): تشخیص خودکار اینکه آیا پشتیبانی از رنگ در ترمینال موجود است یا خیر.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBalways\fR: همیشه رنگ‌ها نمایش داده شوند.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBnever\fR: هرگز رنگ‌ها نمایش داده نشوند.
.RE
.sp
همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.color\fR در <https://doc.rust\-lang.org/cargo/reference/config.html> تعیین شود\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
قالب خروجی برای پیام‌های عیب‌یابی (diagnostic). می‌تواند چندین بار مشخص شود و شامل مقادیری است که با کاما از هم جدا شده‌اند. مقادیر معتبر:
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBhuman\fR (پیش‌فرض): نمایش در یک قالب متنی خوانا برای انسان. با \fBshort\fR و \fBjson\fR تداخل دارد\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBshort\fR: صدور پیام‌های متنی کوتاه‌تر و خوانا برای انسان. با \fBhuman\fR و \fBjson\fR تداخل دارد\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBjson\fR: صدور پیام‌های JSON در stdout. برای جزئیات بیشتر به
\fIمرجع\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
مراجعه کنید. با \fBhuman\fR و \fBshort\fR تداخل دارد\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBjson\-diagnostic\-short\fR: اطمینان حاصل می‌کند که فیلد \fBrendered\fR در پیام‌های JSON شامل نسخهٔ \[lq]کوتاه\[rq] (short) تولیدشده توسط rustc باشد. همراه با \fBhuman\fR یا \fBshort\fR قابل استفاده نیست\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBjson\-diagnostic\-rendered\-ansi\fR: اطمینان حاصل می‌کند که فیلد \fBrendered\fR در پیام‌های JSON حاوی کدهای رنگی توکار ANSI برای حفظ طرح رنگ پیش‌فرض rustc باشد. همراه با \fBhuman\fR یا \fBshort\fR قابل استفاده نیست\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBjson\-render\-diagnostics\fR: به Cargo دستور می‌دهد که پیام‌های عیب‌یابی rustc را در پیام‌های JSON چاپ‌شده نگنجاند، بلکه خود Cargo عیب‌یابی‌های JSON ارسالی از rustc را رندر کند. پیام‌های عیب‌یابی JSON اختصاصی خود Cargo و سایر موارد ارسالی از rustc همچنان صادر می‌شوند. همراه با \fBhuman\fR یا \fBshort\fR قابل استفاده نیست\&.
.RE
.RE
.SS "گزینه‌های مانیفست (Manifest Options)"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
مسیر فایل \fBCargo.toml\fR. به‌طور پیش‌فرض، Cargo فایل \fBCargo.toml\fR را در دایرکتوری جاری یا هر دایرکتوری والد جستجو می‌کند.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
نادیده گرفتن مشخصهٔ \fBrust\-version\fR در بسته‌ها.
.RE
.sp
\fB\-\-locked\fR
.RS 4
تأیید می‌کند که دقیقاً از همان وابستگی‌ها و نسخه‌هایی استفاده شود که هنگام ایجاد فایل \fBCargo.lock\fR اولیه استفاده شده بود. اگر هر یک از سناریوهای زیر رخ دهد، Cargo با خطا خارج خواهد شد:
.sp
.RS 4
\h'-04'\(bu\h'+03'فایل lock موجود نباشد.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'کارگو به دلیل تفکیک وابستگی متفاوتی، برای تغییر فایل lock تلاش کند.
.RE
.sp
ممکن است در محیط‌هایی که ساخت‌های قطعی و تکرارپذیر مورد نظر است، مانند خطوط لوله CI، استفاده شود.
.RE
.sp
\fB\-\-offline\fR
.RS 4
از دسترسی Cargo به شبکه به هر دلیلی جلوگیری می‌کند. بدون این گزینه، اگر Cargo نیاز به دسترسی به شبکه داشته باشد و شبکه در دسترس نباشد، با خطا متوقف خواهد شد. با این گزینه، Cargo تلاش خواهد کرد در صورت امکان بدون شبکه به کار خود ادامه دهد.
.sp
توجه داشته باشید که این عمل ممکن است به تفکیک وابستگی متفاوتی نسبت به حالت آنلاین منجر شود. Cargo خود را به crateهایی محدود می‌کند که به‌صورت محلی دانلود شده‌اند، حتی اگر طبق نسخهٔ محلی index، نسخهٔ جدیدتری موجود باشد. برای دانلود وابستگی‌ها قبل از رفتن به حالت آفلاین، دستور \fBcargo\-fetch\fR(1) را ببینید.
.sp
همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBnet.offline\fR در <https://doc.rust\-lang.org/cargo/reference/config.html> تعیین شود\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
معادل مشخص کردن هم‌زمان هر دو گزینهٔ \fB\-\-locked\fR و \fB\-\-offline\fR\&.
.RE.SS "گزینه‌های مشترک (Common Options)"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
اگر Cargo با rustup نصب شده باشد و اولین آرگومان \fBcargo\fR با \fB+\fR
آغاز شود، به عنوان نام زنجیره‌ابزار (toolchain) در rustup تفسیر خواهد شد (مانند
\fB+stable\fR یا \fB+nightly\fR).
برای اطلاعات بیشتر درباره نحوه کارکرد بازنویسی زنجیره‌ابزار،
\fIمستندات rustup\fR <https://rust\-lang.github.io/rustup/overrides.html>
را ببینید.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR یا \fIPATH\fR
.RS 4
یک مقدار پیکربندی Cargo را بازنویسی می‌کند. آرگومان باید در ساختار TOML به‌صورت \fBKEY=VALUE\fR
یا به عنوان مسیری به یک فایل پیکربندی اضافی ارائه شود. این پرچم می‌تواند چندین بار مشخص شود.
برای اطلاعات بیشتر، \fIبخش بازنویسی‌های خط فرمان\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> را ببینید.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
پیش از اجرای هر عملیات مشخص‌شده، دایرکتوری کاری فعلی را تغییر می‌دهد. این گزینه بر
مواردی مانند جایی که cargo به‌طور پیش‌فرض به دنبال مانیفست پروژه (\fBCargo.toml\fR) می‌گردد،
و همچنین دایرکتوری‌های جستجو شده برای یافتن \fB\&.cargo/config.toml\fR تأثیر می‌گذارد. این گزینه باید
پیش از نام دستور بیاید، برای مثال: \fBcargo \-C path/to/my\-project build\fR\&.
.sp
این گزینه فقط در \fIکانال nightly\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
در دسترس است و برای فعال‌سازی به پرچم \fB\-Z unstable\-options\fR نیاز دارد (ببینید
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR, 
\fB\-\-help\fR
.RS 4
اطلاعات راهنما را نمایش می‌دهد.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
پرچم‌های ناپایدار (فقط nightly) برای Cargo. برای جزئیات، دستور \fBcargo \-Z help\fR را اجرا کنید.
.RE
.SS "گزینه‌های متفرقه (Miscellaneous Options)"
.sp
\fB\-j\fR \fIN\fR, 
\fB\-\-jobs\fR \fIN\fR
.RS 4
تعداد وظایف موازی برای اجرا. همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBbuild.jobs\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&
تعیین شود. پیش‌فرض آن تعداد پردازنده‌های منطقی است. در صورت منفی بودن، حداکثر تعداد
وظایف موازی را روی تعداد پردازنده‌های منطقی به علاوه مقدار مشخص‌شده تنظیم می‌کند. اگر
رشته \fBdefault\fR ارائه شود، مقدار را به حالت پیش‌فرض بازمی‌گرداند.
نباید 0 باشد.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
به جای متوقف کردن ساخت با بروز اولین خطا، تا جای ممکن بسته‌ها (crates) موجود در گراف وابستگی را می‌سازد.
.sp
برای مثال اگر بسته فعلی به وابستگی‌های \fBfails\fR و \fBworks\fR وابسته باشد و ساخت یکی از آن‌ها شکست بخورد،
دستور \fBcargo doc \-j1\fR ممکن است بسته‌ای را که موفق می‌شود بسازد یا نسازد (بسته به این که Cargo ساخت کدام‌یک را اول
انتخاب کرده باشد)، در حالی که \fBcargo doc \-j1 \-\-keep\-going\fR قطعاً هر دو ساخت را اجرا خواهد کرد،
حتی اگر ساخت بسته‌ای که اول اجرا شده شکست بخورد.
.RE
.SH "محیط (ENVIRONMENT)"
برای جزئیات بیشتر درباره متغیرهای محیطی که Cargo می‌خواند، \fIمرجع\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> را
ببینید.
.SH "وضعیت خروج (EXIT STATUS)"
.sp
.RS 4
\h'-04'\(bu\h'+03'\fB0\fR: عملیات Cargo با موفقیت به پایان رسید.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fB101\fR: عملیات Cargo با شکست مواجه شد.
.RE
.SH "مثال‌ها (EXAMPLES)"
.sp
.RS 4
\h'-04' 1.\h'+01'مستندات بسته محلی و وابستگی‌های آن را بسازید و در
\fBtarget/doc\fR خروجی دهید:
.sp
.RS 4
.nf
cargo doc
.fi
.RE
.RE.SH "همچنین ببینید (SEE ALSO)"
\fBcargo\fR(1), \fBcargo\-rustdoc\fR(1), \fBrustdoc\fR(1)