'\" t .TH "CARGO\-RUSTDOC" "1" .nh .ad l .ss \n[.ss] 0 .SH "نام (NAME)" cargo\-rustdoc \- ساخت مستندات یک بسته، با استفاده از پرچم‌های سفارشی مشخص‌شده .SH "خلاصه دستور (SYNOPSIS)" \fBcargo rustdoc\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] .SH "توضیحات (DESCRIPTION)" هدف مشخص‌شده برای بسته جاری (یا بسته مشخص‌شده با \fB\-p\fR در صورت ارائه) مستندسازی خواهد شد و \fIargs\fR مشخص‌شده به فراخوانی نهایی rustdoc ارسال می‌شود. وابستگی‌ها به عنوان بخشی از این دستور مستندسازی نخواهند شد. توجه داشته باشید که rustdoc همچنان بدون قید و شرط آرگومان‌هایی مانند \fB\-L\fR، \fB\-\-extern\fR و \fB\-\-crate\-type\fR را دریافت خواهد کرد، و \fIargs\fR مشخص‌شده صرفاً به فراخوانی rustdoc اضافه خواهد شد. .sp برای مستندات مربوط به پرچم‌های rustdoc، به مراجعه کنید. .sp این دستور مستلزم آن است که در صورت ارائه آرگومان‌های اضافی، فقط یک هدف کامپایل شود. اگر بیش از یک هدف برای بسته جاری در دسترس باشد، باید از فیلترهای \fB\-\-lib\fR، \fB\-\-bin\fR و غیره برای انتخاب هدف مورد نظر جهت کامپایل استفاده شود. .sp برای ارسال پرچم‌ها به تمام فرایندهای rustdoc ایجادشده توسط Cargo، از \fIمتغیر محیطی\fR \fBRUSTDOCFLAGS\fR یا \fIمقدار پیکربندی\fR \fBbuild.rustdocflags\fR \& استفاده کنید. .SH "گزینه‌ها (OPTIONS)" .SS "گزینه‌های مستندسازی (Documentation Options)" .sp \fB\-\-open\fR .RS 4 مستندات را پس از ساخت در یک مرورگر باز می‌کند. این گزینه از مرورگر پیش‌فرض شما استفاده خواهد کرد مگر اینکه مرورگر دیگری را در متغیر محیطی \fBBROWSER\fR تعریف کنید یا از گزینه پیکربندی \fI\f(BIdoc.browser\fI\fR استفاده نمایید. .RE .SS "انتخاب بسته (Package Selection)" به‌طور پیش‌فرض، بسته موجود در دایرکتوری کاری فعلی انتخاب می‌شود. پرچم \fB\-p\fR می‌تواند برای انتخاب بسته‌ای دیگر در یک فضای کاری (workspace) استفاده شود. .sp \fB\-p\fR \fIspec\fR, \fB\-\-package\fR \fIspec\fR .RS 4 بسته‌ای که باید مستندسازی شود. برای ساختار SPEC به \fBcargo\-pkgid\fR(1) مراجعه کنید. .RE .SS "انتخاب هدف (Target Selection)" زمانی که هیچ گزینه انتخاب هدفی مشخص نشده باشد، \fBcargo rustdoc\fR تمام هدف‌های باینری و کتابخانه‌ای بسته انتخاب‌شده را مستندسازی می‌کند. اگر نام باینری با نام هدف کتابخانه یکسان باشد، از آن باینری صرف‌نظر خواهد شد. همچنین اگر باینری‌ها دارای \fBrequired\-features\fR باشند که ناموجودند، از آن‌ها نیز صرف‌نظر می‌شود. .sp ارسال پرچم‌های انتخاب هدف، تنها هدف‌های مشخص‌شده را مستندسازی می‌کند. .sp توجه داشته باشید که پرچم‌های \fB\-\-bin\fR، \fB\-\-example\fR، \fB\-\-test\fR و \fB\-\-bench\fR از الگوهای جانشینی رایج یونیکس (Unix glob patterns) مانند \fB*\fR، \fB?\fR و \fB[]\fR\& نیز پشتیبانی می‌کنند. با این حال، برای جلوگیری از بسط تصادفی الگوهای جانشینی توسط پوسته پیش از پردازش آن‌ها توسط Cargo، باید در اطراف هر الگوی جانشینی از علامت نقل‌قول تکی یا دوگانه استفاده کنید. .sp \fB\-\-lib\fR .RS 4 کتابخانه بسته را مستندسازی می‌کند. .RE .sp \fB\-\-bin\fR \fIname\fR\[u2026] .RS 4 باینری مشخص‌شده را مستندسازی می‌کند. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای جانشینی رایج یونیکس پشتیبانی می‌کند. .RE .sp \fB\-\-bins\fR .RS 4 تمام هدف‌های باینری را مستندسازی می‌کند. .RE .sp \fB\-\-example\fR \fIname\fR\[u2026] .RS 4 مثال مشخص‌شده را مستندسازی می‌کند. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای جانشینی رایج یونیکس پشتیبانی می‌کند. .RE .sp \fB\-\-examples\fR .RS 4 تمام هدف‌های مثال را مستندسازی می‌کند. .RE .sp \fB\-\-test\fR \fIname\fR\[u2026] .RS 4 آزمون یکپارچه‌سازی مشخص‌شده را مستندسازی می‌کند. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای جانشینی رایج یونیکس پشتیبانی می‌کند. .RE .sp \fB\-\-tests\fR .RS 4 تمام هدف‌هایی را که پرچم مانیفست \fBtest = true\fR برای آن‌ها تنظیم شده است، مستندسازی می‌کند. به‌طور پیش‌فرض این شامل کتابخانه و باینری‌های ساخته‌شده به عنوان آزمون واحد، و آزمون‌های یکپارچه‌سازی است. توجه داشته باشید که این کار تمام وابستگی‌های مورد نیاز را نیز می‌سازد، بنابراین هدف کتابخانه ممکن است دوبار ساخته شود (یک‌بار به عنوان آزمون واحد، و بار دیگر به عنوان وابستگی برای باینری‌ها، آزمون‌های یکپارچه‌سازی و غیره). هدف‌ها را می‌توان با تنظیم پرچم \fBtest\fR در تنظیمات مانیفست مربوط به آن هدف فعال یا غیرفعال کرد. .RE .sp \fB\-\-bench\fR \fIname\fR\[u2026] .RS 4 محک (benchmark) مشخص‌شده را مستندسازی می‌کند. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای جانشینی رایج یونیکس پشتیبانی می‌کند. .RE .sp \fB\-\-benches\fR .RS 4 تمام هدف‌هایی را که پرچم مانیفست \fBbench = true\fR برای آن‌ها تنظیم شده است، مستندسازی می‌کند. به‌طور پیش‌فرض این شامل کتابخانه و باینری‌های ساخته‌شده به عنوان محک، و هدف‌های bench است. توجه داشته باشید که این کار تمام وابستگی‌های مورد نیاز را نیز می‌سازد، بنابراین هدف کتابخانه ممکن است دوبار ساخته شود (یک‌بار به عنوان محک، و بار دیگر به عنوان وابستگی برای باینری‌ها، محک‌ها و غیره). هدف‌ها را می‌توان با تنظیم پرچم \fBbench\fR در تنظیمات مانیفست مربوط به آن هدف فعال یا غیرفعال کرد. .RE .sp \fB\-\-all\-targets\fR .RS 4 تمام هدف‌ها را مستندسازی می‌کند. این معادل مشخص‌کردن \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\& است. .RE.SS "انتخاب ویژگی‌ها (Feature Selection)" پرچم‌های ویژگی به شما امکان می‌دهند کنترل کنید کدام ویژگی‌ها فعال شوند. هنگامی که هیچ گزینه‌ای برای ویژگی‌ها داده نشود، ویژگی \fBdefault\fR برای هر بستهٔ انتخاب‌شده فعال می‌شود. .sp برای جزئیات بیشتر، \fIمستندات ویژگی‌ها\fR را ببینید. .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 تولید مستندات برای معماری مقصد مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود. پیش‌فرض، معماری میزبان است. قالب کلی این سه‌گانه عبارت است از \fB\-\-\-\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، که در داخل با مقصد سیستم میزبان جایگزین خواهد شد. این گزینه به ویژه هنگامی مفید است که در حال کامپایل متقابل برخی crateها هستید و نمی‌خواهید ماشین میزبان خود را به عنوان یک مقصد مشخص کنید (برای نمونه، یک \fBxtask\fR در یک پروژهٔ مشترک که ممکن است توسط چندین میزبان روی آن کار شود). .RE .sp .RS 4 \h'-04'\(bu\h'+03'مسیری به مشخصات یک مقصد سفارشی. برای اطلاعات بیشتر، \fICustom Target Lookup Path\fR را ببینید. .RE .sp این مورد را همچنین می‌توان با \fIمقدار پیکربندی\fR \fBbuild.target\fR \& مشخص کرد. .sp توجه داشته باشید که تعیین این پرچم باعث می‌شود Cargo در حالت متفاوتی اجرا شود که در آن مصنوعات مقصد در یک دایرکتوری جداگانه قرار می‌گیرند. برای جزئیات بیشتر، مستندات \fIbuild cache\fR را ببینید. .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 را ببینید. .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 \& مشخص شود. پیش‌فرض، پوشهٔ \fBtarget\fR در ریشهٔ فضای‌کاری است. .RE.SS "گزینه‌های نمایش (Display Options)" .sp \fB\-v\fR, \fB\-\-verbose\fR .RS 4 استفاده از خروجی پرگو (verbose). می‌تواند دو بار برای خروجی \[lq]بسیار پرگو\[rq] مشخص شود که شامل خروجی‌های اضافی مانند هشدارهای وابستگی و خروجی اسکریپت ساخت است. همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.verbose\fR \& مشخص شود. .RE .sp \fB\-q\fR, \fB\-\-quiet\fR .RS 4 عدم چاپ پیام‌های گزارش (log) مربوط به cargo. همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.quiet\fR \& مشخص شود. .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 \& مشخص شود. .RE .sp \fB\-\-message\-format\fR \fIfmt\fR .RS 4 قالب خروجی برای پیام‌های عیب‌یابی. می‌تواند چندین بار مشخص شود و شامل مقادیری است که با کاما از هم جدا شده‌اند. مقادیر معتبر: .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 مراجعه کنید. با \fBhuman\fR و \fBshort\fR تداخل دارد. .RE .sp .RS 4 \h'-04'\(bu\h'+03'\fBjson\-diagnostic\-short\fR: اطمینان حاصل می‌کند که فیلد \fBrendered\fR در پیام‌های JSON شامل رندرینگ \[lq]کوتاه\[rq] از 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'دستور Cargo به دلیل حل وابستگی متفاوت، تلاش کند فایل lock را تغییر دهد. .RE .sp این گزینه می‌تواند در محیط‌هایی که نیاز به ساخت‌های قطعی و تکرارپذیر دارند، مانند خطوط لولهٔ CI، استفاده شود. .RE .sp \fB\-\-offline\fR .RS 4 از دسترسی Cargo به شبکه به هر دلیلی جلوگیری می‌کند. بدون این پرچم، اگر Cargo نیاز به دسترسی به شبکه داشته باشد و شبکه در دسترس نباشد، با خطا متوقف خواهد شد. با این پرچم، Cargo در صورت امکان تلاش خواهد کرد بدون شبکه به کار خود ادامه دهد. .sp توجه داشته باشید که این ممکن است به حل وابستگی متفاوتی نسبت به حالت برخط منجر شود. Cargo خود را به crateهایی که به صورت محلی بارگیری شده‌اند محدود می‌کند، حتی اگر طبق نسخهٔ محلی نمایه، نسخهٔ جدیدتری موجود باشد. برای بارگیری وابستگی‌ها قبل از رفتن به حالت آفلاین، دستور \fBcargo\-fetch\fR(1) را ببینید. .sp همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBnet.offline\fR \& مشخص شود. .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) تفسیر خواهد شد. برای اطلاعات بیشتر درباره نحوه کارکرد رونویسی‌های toolchain، \fIمستندات rustup\fR را ببینید. .RE .sp \fB\-\-config\fR \fIKEY=VALUE\fR یا \fIPATH\fR .RS 4 یک مقدار پیکربندی Cargo را رونویسی می‌کند. آرگومان باید در نحو TOML به‌صورت \fBKEY=VALUE\fR باشد، یا به‌صورت مسیر یک فایل پیکربندی اضافی ارائه شود. این پرچم را می‌توان چندین بار مشخص کرد. برای اطلاعات بیشتر، \fIبخش رونویسی‌های خط فرمان\fR را ببینید. .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 در دسترس است و برای فعال‌سازی نیازمند پرچم \fB\-Z unstable\-options\fR است (\fI#10098\fR را ببینید). .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 \& مشخص شود. پیش‌فرض، تعداد پردازنده‌های منطقی است. در صورت منفی بودن، حداکثر تعداد کارهای موازی را برابر با تعداد پردازنده‌های منطقی به‌علاوه مقدار ارائه‌شده قرار می‌دهد. در صورت ارائه رشته \fBdefault\fR، مقدار به پیش‌فرض بازمی‌گردد. نباید 0 باشد. .RE .sp \fB\-\-keep\-going\fR .RS 4 تا جای ممکن crateهای بیشتری را در گراف وابستگی می‌سازد، به‌جای اینکه با شکست اولین مورد در ساخت، عملیات متوقف شود. .sp برای مثال اگر بسته فعلی به وابستگی‌های \fBfails\fR و \fBworks\fR وابسته باشد و ساخت یکی از آن‌ها با خطا مواجه شود، ممکن است \fBcargo rustdoc \-j1\fR وابستگی موفق را بسازد یا نسازد (بسته به اینکه Cargo کدام‌یک از دو ساخت را ابتدا برای اجرا انتخاب کرده باشد)، در حالی که \fBcargo rustdoc \-j1 \-\-keep\-going\fR قطعاً هر دو ساخت را اجرا خواهد کرد، حتی اگر موردی که اول اجرا می‌شود شکست بخورد. .RE .sp \fB\-\-output\-format\fR .RS 4 نوع خروجی برای مستندات تولیدشده. مقادیر معتبر: .sp .RS 4 \h'-04'\(bu\h'+03'\fBhtml\fR (پیش‌فرض): تولید مستندات در قالب HTML. .RE .sp .RS 4 \h'-04'\(bu\h'+03'\fBjson\fR: تولید مستندات در \fIقالب آزمایشی JSON\fR \&. .RE .sp این گزینه تنها در \fIکانال nightly\fR در دسترس است و برای فعال‌سازی به پرچم \fB\-Z unstable\-options\fR نیاز دارد. .RE.SH "محیط (ENVIRONMENT)" برای جزئیات دربارهٔ متغیرهای محیطی که Cargo می‌خواند، \fIمرجع\fR را ببینید. .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'ساخت مستندات به همراه CSS سفارشی اضافه‌شده از یک فایل مشخص: .sp .RS 4 .nf cargo rustdoc \-\-lib \-\- \-\-extend\-css extra.css .fi .RE .RE .SH "همچنین ببینید (SEE ALSO)" \fBcargo\fR(1), \fBcargo\-doc\fR(1), \fBrustdoc\fR(1)