CARGO-DOC(1) General Commands Manual CARGO-DOC(1)

cargo-doc - ساخت مستندات یک بسته

cargo doc [گزینه‌ها]

مستندات بستهٔ محلی و تمام وابستگی‌ها را می‌سازد. خروجی در target/doc با قالب معمول rustdoc قرار می‌گیرد.

نکته: تولید مستندات به‌صورت تجمعی است: فایل‌های مستندات موجود در دایرکتوری هدف در میان فراخوانی‌های مختلف cargo doc حفظ می‌شوند. برای حذف مستندات تولیدشدهٔ پیشین، گزینهٔ --doc را به cargo-clean(1) بدهید.

--open

باز کردن مستندات در یک مرورگر پس از ساخت آن‌ها. این دستور از مرورگر پیش‌فرض شما استفاده خواهد کرد مگر اینکه مرورگر دیگری را در متغیر محیطی BROWSER مشخص کرده باشید یا از گزینهٔ پیکربندی doc.browser https://doc.rust-lang.org/cargo/reference/config.html#docbrowser استفاده کنید.

--no-deps

برای وابستگی‌ها مستندات نساز.

--document-private-items

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

به‌طور پیش‌فرض، هنگامی که هیچ گزینه‌ای برای انتخاب بسته داده نشده باشد، بسته‌های انتخاب‌شده به فایل مانیفستِ انتخاب‌شده بستگی دارند (بر پایهٔ دایرکتوری کاری جاری، در صورتی که --manifest-path داده نشده باشد). اگر مانیفست، ریشهٔ یک فضای کاری (workspace) باشد، اعضای پیش‌فرض فضای کاری انتخاب می‌شوند، در غیر این صورت تنها بسته‌ای که توسط مانیفست تعریف شده است انتخاب خواهد شد.

اعضای پیش‌فرض یک فضای کاری را می‌توان به‌طور صریح با کلید workspace.default-members در مانیفست ریشه مشخص کرد. در صورت عدم تنظیم، یک فضای کاری مجازی شامل همهٔ اعضای فضای کاری خواهد بود (معادل ارسال --workspace)، و یک فضای کاری غیرمجازی فقط شامل خودِ کریت (crate) ریشه خواهد بود.

-p spec…, --package spec…

فقط بسته‌های مشخص‌شده را مستندسازی کن. برای قالب SPEC به cargo-pkgid(1) مراجعه کنید. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس مانند *، ? و [] پشتیبانی می‌کند. با این وجود، برای جلوگیری از بسط تصادفی الگوهای glob توسط شل پیش از پردازش آن‌ها توسط Cargo، باید در دو طرف هر الگو از علامت‌های نقل‌قول تکی یا جفتی استفاده کنید.

--workspace

مستندسازی تمام اعضا در فضای کاری.

--all

نام مستعار منسوخ‌شده برای --workspace.

--exclude SPEC…

مستثنی کردن بسته‌های مشخص‌شده. باید در کنار پرچم --workspace استفاده شود. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس مانند *، ? و [] پشتیبانی می‌کند. با این حال، برای جلوگیری از بسط تصادفی الگوهای glob توسط شل پیش از پردازش آن‌ها توسط Cargo، باید در دو طرف هر الگو از علامت‌های نقل‌قول تکی یا جفتی استفاده کنید.

هنگامی که گزینه‌ای برای انتخاب هدف داده نشود، cargo doc تمام اهداف باینری و کتابخانه‌ایِ بستهٔ انتخاب‌شده را مستندسازی خواهد کرد. اگر نام هدف باینری با هدف کتابخانه (lib) یکسان باشد، از باینری صرف‌نظر می‌شود. باینری‌هایی که ویژگی‌های الزامی (required-features) ناموجود داشته باشند نیز نادیده گرفته می‌شوند.

رفتار پیش‌فرض را می‌توان با تنظیم doc = false برای هدف در تنظیمات مانیفست تغییر داد. استفاده از گزینه‌های انتخاب هدف، پرچم doc را نادیده می‌گیرد و همواره هدف داده‌شده را مستندسازی می‌کند.

--lib

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

--bin name…

مستندسازی باینری مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس پشتیبانی می‌کند.

--bins

مستندسازی تمام اهداف باینری.

--example name…

مستندسازی نمونهٔ (example) مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس پشتیبانی می‌کند.

--examples

مستندسازی تمام اهداف نمونه (examples). پرچم‌های ویژگی به شما اجازه می‌دهند تعیین کنید کدام ویژگی‌ها فعال شوند. زمانی که هیچ گزینهٔ ویژگی مشخص نشده باشد، ویژگی default برای هر بستهٔ انتخاب‌شده فعال می‌شود.

برای جزئیات بیشتر، مستندات ویژگی‌ها را در https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options ببینید.

-F features, --features features

فهرستی از ویژگی‌ها جداشده با فاصله یا کاما جهت فعال‌سازی. ویژگی‌های اعضای فضای کاری را می‌توان با نحو package-name/feature-name فعال کرد. این پرچم می‌تواند چندین بار مشخص شود که تمام ویژگی‌های تعیین‌شده را فعال می‌کند.

--all-features

فعال‌سازی تمام ویژگی‌های موجود در تمامی بسته‌های انتخاب‌شده.

--no-default-features

ویژگی default بسته‌های انتخاب‌شده را فعال نمی‌کند.

--target triple

تولید مستندات برای معماری هدف مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود. مقدار پیش‌فرض، معماری میزبان است. قالب کلی این سه‌تایی (triple) به‌صورت <arch><sub>-<vendor>-<sys>-<abi> است.

مقادیر ممکن:

•هر هدف پشتیبانی‌شده در rustc --print target-list.
•"host-tuple"، که در درون برنامه با هدفِ میزبان جایگزین خواهد شد. این گزینه به‌ویژه زمانی کاربرد دارد که در حال کامپایل متقابل (cross-compilation) برخی کریت‌ها هستید و نمی‌خواهید ماشین میزبان خود را به‌طور صریح به‌عنوان یک هدف مشخص کنید (برای نمونه، یک xtask در پروژه‌ای مشترک که ممکن است توسط چندین میزبان روی آن کار شود).
•مسیری به مشخصات یک هدف سفارشی. برای اطلاعات بیشتر، Custom Target Lookup Path را در https://doc.rust-lang.org/rustc/targets/custom.html#custom-target-lookup-path ببینید.

این مورد را می‌توان با مقدار پیکربندی build.target در https://doc.rust-lang.org/cargo/reference/config.html نیز تعیین کرد.

توجه داشته باشید که مشخص کردن این پرچم باعث می‌شود Cargo در حالت متفاوتی اجرا شود که در آن مصنوعات هدف در یک دایرکتوری جداگانه قرار می‌گیرند. برای جزئیات بیشتر، مستندات حافظه پنهان ساخت (build cache) را در https://doc.rust-lang.org/cargo/reference/build-cache.html ببینید.

-r, --release

تولید مستندات برای مصنوعات بهینه‌سازی‌شده با نمایهٔ release. همچنین گزینهٔ --profile را برای انتخاب یک نمایهٔ خاص بر اساس نام آن ببینید.

--profile name

تولید مستندات با نمایهٔ داده‌شده. برای جزئیات بیشتر دربارهٔ نمایه‌ها، مرجع را در https://doc.rust-lang.org/cargo/reference/profiles.html ببینید.

--timings

اطلاعاتی دربارهٔ مدت‌زمان هر کامپایل خروجی می‌دهد و داده‌های همزمانی را در طول زمان رهگیری می‌کند.

در پایان فرایند ساخت، یک فایل cargo-timing.html در دایرکتوری target/cargo-timings نوشته خواهد شد. در صورتی که بخواهید یک اجرای پیشین را بررسی کنید، گزارش دیگری نیز با یک برچسب زمانی در نام فایل ذخیره می‌شود. این گزارش‌ها تنها برای خوانش انسانی مناسب هستند و داده‌های زمان‌بندیِ ماشین‌خوان ارائه نمی‌دهند.

--target-dir directory

دایرکتوری برای تمامی مصنوعات و فایل‌های واسط تولیدشده. همچنین می‌تواند با متغیر محیطی CARGO_TARGET_DIR یا مقدار پیکربندی build.target-dir در https://doc.rust-lang.org/cargo/reference/config.html تعیین شود. مقدار پیش‌فرض target در ریشهٔ فضای کاری است.

-v, --verbose

استفاده از خروجی پرجزئیات. می‌تواند دو بار برای خروجی “بسیار پرجزئیات” مشخص شود که شامل خروجی‌های اضافی مانند هشدارهای وابستگی و خروجی اسکریپت ساخت است. همچنین می‌تواند با مقدار پیکربندی term.verbose در https://doc.rust-lang.org/cargo/reference/config.html تعیین شود.

-q, --quiet

پیام‌های لاگ Cargo چاپ نشوند. همچنین می‌تواند با مقدار پیکربندی term.quiet در https://doc.rust-lang.org/cargo/reference/config.html تعیین شود.

--color when

کنترل زمان استفاده از خروجی رنگی. مقادیر معتبر:
•auto (پیش‌فرض): تشخیص خودکار اینکه آیا پشتیبانی از رنگ در ترمینال موجود است یا خیر.
•always: همیشه رنگ‌ها نمایش داده شوند.
•never: هرگز رنگ‌ها نمایش داده نشوند.

همچنین می‌تواند با مقدار پیکربندی term.color در https://doc.rust-lang.org/cargo/reference/config.html تعیین شود.

--message-format fmt

قالب خروجی برای پیام‌های عیب‌یابی (diagnostic). می‌تواند چندین بار مشخص شود و شامل مقادیری است که با کاما از هم جدا شده‌اند. مقادیر معتبر:
•human (پیش‌فرض): نمایش در یک قالب متنی خوانا برای انسان. با short و json تداخل دارد.
•short: صدور پیام‌های متنی کوتاه‌تر و خوانا برای انسان. با human و json تداخل دارد.
•json: صدور پیام‌های JSON در stdout. برای جزئیات بیشتر به مرجع https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages مراجعه کنید. با human و short تداخل دارد.
•json-diagnostic-short: اطمینان حاصل می‌کند که فیلد rendered در پیام‌های JSON شامل نسخهٔ “کوتاه” (short) تولیدشده توسط rustc باشد. همراه با human یا short قابل استفاده نیست.
•json-diagnostic-rendered-ansi: اطمینان حاصل می‌کند که فیلد rendered در پیام‌های JSON حاوی کدهای رنگی توکار ANSI برای حفظ طرح رنگ پیش‌فرض rustc باشد. همراه با human یا short قابل استفاده نیست.
•json-render-diagnostics: به Cargo دستور می‌دهد که پیام‌های عیب‌یابی rustc را در پیام‌های JSON چاپ‌شده نگنجاند، بلکه خود Cargo عیب‌یابی‌های JSON ارسالی از rustc را رندر کند. پیام‌های عیب‌یابی JSON اختصاصی خود Cargo و سایر موارد ارسالی از rustc همچنان صادر می‌شوند. همراه با human یا short قابل استفاده نیست.

--manifest-path path

مسیر فایل Cargo.toml. به‌طور پیش‌فرض، Cargo فایل Cargo.toml را در دایرکتوری جاری یا هر دایرکتوری والد جستجو می‌کند.

--ignore-rust-version

نادیده گرفتن مشخصهٔ rust-version در بسته‌ها.

--locked

تأیید می‌کند که دقیقاً از همان وابستگی‌ها و نسخه‌هایی استفاده شود که هنگام ایجاد فایل Cargo.lock اولیه استفاده شده بود. اگر هر یک از سناریوهای زیر رخ دهد، Cargo با خطا خارج خواهد شد:
•فایل lock موجود نباشد.
•کارگو به دلیل تفکیک وابستگی متفاوتی، برای تغییر فایل lock تلاش کند.

ممکن است در محیط‌هایی که ساخت‌های قطعی و تکرارپذیر مورد نظر است، مانند خطوط لوله CI، استفاده شود.

--offline

از دسترسی Cargo به شبکه به هر دلیلی جلوگیری می‌کند. بدون این گزینه، اگر Cargo نیاز به دسترسی به شبکه داشته باشد و شبکه در دسترس نباشد، با خطا متوقف خواهد شد. با این گزینه، Cargo تلاش خواهد کرد در صورت امکان بدون شبکه به کار خود ادامه دهد.

توجه داشته باشید که این عمل ممکن است به تفکیک وابستگی متفاوتی نسبت به حالت آنلاین منجر شود. Cargo خود را به crateهایی محدود می‌کند که به‌صورت محلی دانلود شده‌اند، حتی اگر طبق نسخهٔ محلی index، نسخهٔ جدیدتری موجود باشد. برای دانلود وابستگی‌ها قبل از رفتن به حالت آفلاین، دستور cargo-fetch(1) را ببینید.

همچنین می‌تواند با مقدار پیکربندی net.offline در https://doc.rust-lang.org/cargo/reference/config.html تعیین شود.

--frozen

معادل مشخص کردن هم‌زمان هر دو گزینهٔ --locked و --offline.

+toolchain

اگر Cargo با rustup نصب شده باشد و اولین آرگومان cargo با + آغاز شود، به عنوان نام زنجیره‌ابزار (toolchain) در rustup تفسیر خواهد شد (مانند +stable یا +nightly). برای اطلاعات بیشتر درباره نحوه کارکرد بازنویسی زنجیره‌ابزار، مستندات rustup https://rust-lang.github.io/rustup/overrides.html را ببینید.

--config KEY=VALUE یا PATH

یک مقدار پیکربندی Cargo را بازنویسی می‌کند. آرگومان باید در ساختار TOML به‌صورت KEY=VALUE یا به عنوان مسیری به یک فایل پیکربندی اضافی ارائه شود. این پرچم می‌تواند چندین بار مشخص شود. برای اطلاعات بیشتر، بخش بازنویسی‌های خط فرمان https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides را ببینید.

-C PATH

پیش از اجرای هر عملیات مشخص‌شده، دایرکتوری کاری فعلی را تغییر می‌دهد. این گزینه بر مواردی مانند جایی که cargo به‌طور پیش‌فرض به دنبال مانیفست پروژه (Cargo.toml) می‌گردد، و همچنین دایرکتوری‌های جستجو شده برای یافتن .cargo/config.toml تأثیر می‌گذارد. این گزینه باید پیش از نام دستور بیاید، برای مثال: cargo -C path/to/my-project build.

این گزینه فقط در کانال nightly https://doc.rust-lang.org/book/appendix-07-nightly-rust.html در دسترس است و برای فعال‌سازی به پرچم -Z unstable-options نیاز دارد (ببینید #10098 https://github.com/rust-lang/cargo/issues/10098).

-h, --help

اطلاعات راهنما را نمایش می‌دهد.

-Z flag

پرچم‌های ناپایدار (فقط nightly) برای Cargo. برای جزئیات، دستور cargo -Z help را اجرا کنید.

-j N, --jobs N

تعداد وظایف موازی برای اجرا. همچنین می‌تواند با مقدار پیکربندی build.jobs https://doc.rust-lang.org/cargo/reference/config.html تعیین شود. پیش‌فرض آن تعداد پردازنده‌های منطقی است. در صورت منفی بودن، حداکثر تعداد وظایف موازی را روی تعداد پردازنده‌های منطقی به علاوه مقدار مشخص‌شده تنظیم می‌کند. اگر رشته default ارائه شود، مقدار را به حالت پیش‌فرض بازمی‌گرداند. نباید 0 باشد.

--keep-going

به جای متوقف کردن ساخت با بروز اولین خطا، تا جای ممکن بسته‌ها (crates) موجود در گراف وابستگی را می‌سازد.

برای مثال اگر بسته فعلی به وابستگی‌های fails و works وابسته باشد و ساخت یکی از آن‌ها شکست بخورد، دستور cargo doc -j1 ممکن است بسته‌ای را که موفق می‌شود بسازد یا نسازد (بسته به این که Cargo ساخت کدام‌یک را اول انتخاب کرده باشد)، در حالی که cargo doc -j1 --keep-going قطعاً هر دو ساخت را اجرا خواهد کرد، حتی اگر ساخت بسته‌ای که اول اجرا شده شکست بخورد.

برای جزئیات بیشتر درباره متغیرهای محیطی که Cargo می‌خواند، مرجع https://doc.rust-lang.org/cargo/reference/environment-variables.html را ببینید.

•0: عملیات Cargo با موفقیت به پایان رسید.
•101: عملیات Cargo با شکست مواجه شد.

1.مستندات بسته محلی و وابستگی‌های آن را بسازید و در target/doc خروجی دهید: 
cargo doc
cargo(1), cargo-rustdoc(1), rustdoc(1)