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

cargo-rustdoc - ساخت مستندات یک بسته، با استفاده از پرچم‌های سفارشی مشخص‌شده

cargo rustdoc [options] [-- args]

هدف مشخص‌شده برای بسته جاری (یا بسته مشخص‌شده با -p در صورت ارائه) مستندسازی خواهد شد و args مشخص‌شده به فراخوانی نهایی rustdoc ارسال می‌شود. وابستگی‌ها به عنوان بخشی از این دستور مستندسازی نخواهند شد. توجه داشته باشید که rustdoc همچنان بدون قید و شرط آرگومان‌هایی مانند -L، --extern و --crate-type را دریافت خواهد کرد، و args مشخص‌شده صرفاً به فراخوانی rustdoc اضافه خواهد شد.

برای مستندات مربوط به پرچم‌های rustdoc، به https://doc.rust-lang.org/rustdoc/index.html مراجعه کنید.

این دستور مستلزم آن است که در صورت ارائه آرگومان‌های اضافی، فقط یک هدف کامپایل شود. اگر بیش از یک هدف برای بسته جاری در دسترس باشد، باید از فیلترهای --lib، --bin و غیره برای انتخاب هدف مورد نظر جهت کامپایل استفاده شود.

برای ارسال پرچم‌ها به تمام فرایندهای rustdoc ایجادشده توسط Cargo، از متغیر محیطی RUSTDOCFLAGS https://doc.rust-lang.org/cargo/reference/environment-variables.html یا مقدار پیکربندی build.rustdocflags https://doc.rust-lang.org/cargo/reference/config.html استفاده کنید.

--open

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

به‌طور پیش‌فرض، بسته موجود در دایرکتوری کاری فعلی انتخاب می‌شود. پرچم -p می‌تواند برای انتخاب بسته‌ای دیگر در یک فضای کاری (workspace) استفاده شود.

-p spec, --package spec

بسته‌ای که باید مستندسازی شود. برای ساختار SPEC به cargo-pkgid(1) مراجعه کنید.

زمانی که هیچ گزینه انتخاب هدفی مشخص نشده باشد، cargo rustdoc تمام هدف‌های باینری و کتابخانه‌ای بسته انتخاب‌شده را مستندسازی می‌کند. اگر نام باینری با نام هدف کتابخانه یکسان باشد، از آن باینری صرف‌نظر خواهد شد. همچنین اگر باینری‌ها دارای required-features باشند که ناموجودند، از آن‌ها نیز صرف‌نظر می‌شود.

ارسال پرچم‌های انتخاب هدف، تنها هدف‌های مشخص‌شده را مستندسازی می‌کند.

توجه داشته باشید که پرچم‌های --bin، --example، --test و --bench از الگوهای جانشینی رایج یونیکس (Unix glob patterns) مانند *، ? و [] نیز پشتیبانی می‌کنند. با این حال، برای جلوگیری از بسط تصادفی الگوهای جانشینی توسط پوسته پیش از پردازش آن‌ها توسط Cargo، باید در اطراف هر الگوی جانشینی از علامت نقل‌قول تکی یا دوگانه استفاده کنید.

--lib

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

--bin name…

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

--bins

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

--example name…

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

--examples

تمام هدف‌های مثال را مستندسازی می‌کند.

--test name…

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

--tests

تمام هدف‌هایی را که پرچم مانیفست test = true برای آن‌ها تنظیم شده است، مستندسازی می‌کند. به‌طور پیش‌فرض این شامل کتابخانه و باینری‌های ساخته‌شده به عنوان آزمون واحد، و آزمون‌های یکپارچه‌سازی است. توجه داشته باشید که این کار تمام وابستگی‌های مورد نیاز را نیز می‌سازد، بنابراین هدف کتابخانه ممکن است دوبار ساخته شود (یک‌بار به عنوان آزمون واحد، و بار دیگر به عنوان وابستگی برای باینری‌ها، آزمون‌های یکپارچه‌سازی و غیره). هدف‌ها را می‌توان با تنظیم پرچم test در تنظیمات مانیفست مربوط به آن هدف فعال یا غیرفعال کرد.

--bench name…

محک (benchmark) مشخص‌شده را مستندسازی می‌کند. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای جانشینی رایج یونیکس پشتیبانی می‌کند.

--benches

تمام هدف‌هایی را که پرچم مانیفست bench = true برای آن‌ها تنظیم شده است، مستندسازی می‌کند. به‌طور پیش‌فرض این شامل کتابخانه و باینری‌های ساخته‌شده به عنوان محک، و هدف‌های bench است. توجه داشته باشید که این کار تمام وابستگی‌های مورد نیاز را نیز می‌سازد، بنابراین هدف کتابخانه ممکن است دوبار ساخته شود (یک‌بار به عنوان محک، و بار دیگر به عنوان وابستگی برای باینری‌ها، محک‌ها و غیره). هدف‌ها را می‌توان با تنظیم پرچم bench در تنظیمات مانیفست مربوط به آن هدف فعال یا غیرفعال کرد.

--all-targets

تمام هدف‌ها را مستندسازی می‌کند. این معادل مشخص‌کردن --lib --bins --tests --benches --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

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

مقادیر ممکن:

•هر مقصد پشتیبانی‌شده در rustc --print target-list.
•"host-tuple"، که در داخل با مقصد سیستم میزبان جایگزین خواهد شد. این گزینه به ویژه هنگامی مفید است که در حال کامپایل متقابل برخی crateها هستید و نمی‌خواهید ماشین میزبان خود را به عنوان یک مقصد مشخص کنید (برای نمونه، یک 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

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

-q, --quiet

عدم چاپ پیام‌های گزارش (log) مربوط به 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

قالب خروجی برای پیام‌های عیب‌یابی. می‌تواند چندین بار مشخص شود و شامل مقادیری است که با کاما از هم جدا شده‌اند. مقادیر معتبر:
•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 شامل رندرینگ “کوتاه” از 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 موجود نباشد.
•دستور Cargo به دلیل حل وابستگی متفاوت، تلاش کند فایل lock را تغییر دهد.

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

--offline

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

توجه داشته باشید که این ممکن است به حل وابستگی متفاوتی نسبت به حالت برخط منجر شود. Cargo خود را به crateهایی که به صورت محلی بارگیری شده‌اند محدود می‌کند، حتی اگر طبق نسخهٔ محلی نمایه، نسخهٔ جدیدتری موجود باشد. برای بارگیری وابستگی‌ها قبل از رفتن به حالت آفلاین، دستور 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) تفسیر خواهد شد. برای اطلاعات بیشتر درباره نحوه کارکرد رونویسی‌های toolchain، مستندات 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

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

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

--output-format

نوع خروجی برای مستندات تولیدشده. مقادیر معتبر:
•html (پیش‌فرض): تولید مستندات در قالب HTML.
•json: تولید مستندات در قالب آزمایشی JSON https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types.

این گزینه تنها در کانال nightly https://doc.rust-lang.org/book/appendix-07-nightly-rust.html در دسترس است و برای فعال‌سازی به پرچم -Z unstable-options نیاز دارد. برای جزئیات دربارهٔ متغیرهای محیطی که Cargo می‌خواند، مرجع https://doc.rust-lang.org/cargo/reference/environment-variables.html را ببینید.

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

1.ساخت مستندات به همراه CSS سفارشی اضافه‌شده از یک فایل مشخص: 
cargo rustdoc --lib -- --extend-css extra.css

cargo(1), cargo-doc(1), rustdoc(1)