1# cargo-doc(1) 2 3 4## NAME 5 6cargo-doc - Build a package's documentation 7 8## SYNOPSIS 9 10`cargo doc` [_options_] 11 12## DESCRIPTION 13 14Build the documentation for the local package and all dependencies. The output 15is placed in `target/doc` in rustdoc's usual format. 16 17## OPTIONS 18 19### Documentation Options 20 21<dl> 22 23<dt class="option-term" id="option-cargo-doc---open"><a class="option-anchor" href="#option-cargo-doc---open"></a><code>--open</code></dt> 24<dd class="option-desc">Open the docs in a browser after building them. This will use your default 25browser unless you define another one in the <code>BROWSER</code> environment variable 26or use the <a href="../reference/config.html#docbrowser"><code>doc.browser</code></a> configuration 27option.</dd> 28 29 30<dt class="option-term" id="option-cargo-doc---no-deps"><a class="option-anchor" href="#option-cargo-doc---no-deps"></a><code>--no-deps</code></dt> 31<dd class="option-desc">Do not build documentation for dependencies.</dd> 32 33 34<dt class="option-term" id="option-cargo-doc---document-private-items"><a class="option-anchor" href="#option-cargo-doc---document-private-items"></a><code>--document-private-items</code></dt> 35<dd class="option-desc">Include non-public items in the documentation. This will be enabled by default if documenting a binary target.</dd> 36 37 38</dl> 39 40### Package Selection 41 42By default, when no package selection options are given, the packages selected 43depend on the selected manifest file (based on the current working directory if 44`--manifest-path` is not given). If the manifest is the root of a workspace then 45the workspaces default members are selected, otherwise only the package defined 46by the manifest will be selected. 47 48The default members of a workspace can be set explicitly with the 49`workspace.default-members` key in the root manifest. If this is not set, a 50virtual workspace will include all workspace members (equivalent to passing 51`--workspace`), and a non-virtual workspace will include only the root crate itself. 52 53<dl> 54 55<dt class="option-term" id="option-cargo-doc--p"><a class="option-anchor" href="#option-cargo-doc--p"></a><code>-p</code> <em>spec</em>...</dt> 56<dt class="option-term" id="option-cargo-doc---package"><a class="option-anchor" href="#option-cargo-doc---package"></a><code>--package</code> <em>spec</em>...</dt> 57<dd class="option-desc">Document only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the 58SPEC format. This flag may be specified multiple times and supports common Unix 59glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally 60expanding glob patterns before Cargo handles them, you must use single quotes or 61double quotes around each pattern.</dd> 62 63 64<dt class="option-term" id="option-cargo-doc---workspace"><a class="option-anchor" href="#option-cargo-doc---workspace"></a><code>--workspace</code></dt> 65<dd class="option-desc">Document all members in the workspace.</dd> 66 67 68 69<dt class="option-term" id="option-cargo-doc---all"><a class="option-anchor" href="#option-cargo-doc---all"></a><code>--all</code></dt> 70<dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd> 71 72 73 74<dt class="option-term" id="option-cargo-doc---exclude"><a class="option-anchor" href="#option-cargo-doc---exclude"></a><code>--exclude</code> <em>SPEC</em>...</dt> 75<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the 76<code>--workspace</code> flag. This flag may be specified multiple times and supports 77common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell 78accidentally expanding glob patterns before Cargo handles them, you must use 79single quotes or double quotes around each pattern.</dd> 80 81 82</dl> 83 84 85### Target Selection 86 87When no target selection options are given, `cargo doc` will document all 88binary and library targets of the selected package. The binary will be skipped 89if its name is the same as the lib target. Binaries are skipped if they have 90`required-features` that are missing. 91 92The default behavior can be changed by setting `doc = false` for the target in 93the manifest settings. Using target selection options will ignore the `doc` 94flag and will always document the given target. 95 96<dl> 97<dt class="option-term" id="option-cargo-doc---lib"><a class="option-anchor" href="#option-cargo-doc---lib"></a><code>--lib</code></dt> 98<dd class="option-desc">Document the package's library.</dd> 99 100 101<dt class="option-term" id="option-cargo-doc---bin"><a class="option-anchor" href="#option-cargo-doc---bin"></a><code>--bin</code> <em>name</em>...</dt> 102<dd class="option-desc">Document the specified binary. This flag may be specified multiple times 103and supports common Unix glob patterns.</dd> 104 105 106<dt class="option-term" id="option-cargo-doc---bins"><a class="option-anchor" href="#option-cargo-doc---bins"></a><code>--bins</code></dt> 107<dd class="option-desc">Document all binary targets.</dd> 108 109 110 111<dt class="option-term" id="option-cargo-doc---example"><a class="option-anchor" href="#option-cargo-doc---example"></a><code>--example</code> <em>name</em>...</dt> 112<dd class="option-desc">Document the specified example. This flag may be specified multiple times 113and supports common Unix glob patterns.</dd> 114 115 116<dt class="option-term" id="option-cargo-doc---examples"><a class="option-anchor" href="#option-cargo-doc---examples"></a><code>--examples</code></dt> 117<dd class="option-desc">Document all example targets.</dd> 118 119 120</dl> 121 122### Feature Selection 123 124The feature flags allow you to control which features are enabled. When no 125feature options are given, the `default` feature is activated for every 126selected package. 127 128See [the features documentation](../reference/features.html#command-line-feature-options) 129for more details. 130 131<dl> 132 133<dt class="option-term" id="option-cargo-doc---features"><a class="option-anchor" href="#option-cargo-doc---features"></a><code>--features</code> <em>features</em></dt> 134<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace 135members may be enabled with <code>package-name/feature-name</code> syntax. This flag may 136be specified multiple times, which enables all specified features.</dd> 137 138 139<dt class="option-term" id="option-cargo-doc---all-features"><a class="option-anchor" href="#option-cargo-doc---all-features"></a><code>--all-features</code></dt> 140<dd class="option-desc">Activate all available features of all selected packages.</dd> 141 142 143<dt class="option-term" id="option-cargo-doc---no-default-features"><a class="option-anchor" href="#option-cargo-doc---no-default-features"></a><code>--no-default-features</code></dt> 144<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> 145 146 147</dl> 148 149 150### Compilation Options 151 152<dl> 153 154<dt class="option-term" id="option-cargo-doc---target"><a class="option-anchor" href="#option-cargo-doc---target"></a><code>--target</code> <em>triple</em></dt> 155<dd class="option-desc">Document for the given architecture. The default is the host 156architecture. The general format of the triple is 157<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a 158list of supported targets.</p> 159<p>This may also be specified with the <code>build.target</code> 160<a href="../reference/config.html">config value</a>.</p> 161<p>Note that specifying this flag makes Cargo run in a different mode where the 162target artifacts are placed in a separate directory. See the 163<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> 164 165 166 167<dt class="option-term" id="option-cargo-doc---release"><a class="option-anchor" href="#option-cargo-doc---release"></a><code>--release</code></dt> 168<dd class="option-desc">Document optimized artifacts with the <code>release</code> profile. 169See also the <code>--profile</code> option for choosing a specific profile by name.</dd> 170 171 172 173<dt class="option-term" id="option-cargo-doc---profile"><a class="option-anchor" href="#option-cargo-doc---profile"></a><code>--profile</code> <em>name</em></dt> 174<dd class="option-desc">Document with the given profile. 175See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> 176 177 178 179<dt class="option-term" id="option-cargo-doc---ignore-rust-version"><a class="option-anchor" href="#option-cargo-doc---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> 180<dd class="option-desc">Document the target even if the selected Rust compiler is older than the 181required Rust version as configured in the project's <code>rust-version</code> field.</dd> 182 183 184 185</dl> 186 187### Output Options 188 189<dl> 190<dt class="option-term" id="option-cargo-doc---target-dir"><a class="option-anchor" href="#option-cargo-doc---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> 191<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be 192specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the 193<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. 194Defaults to <code>target</code> in the root of the workspace.</dd> 195 196 197</dl> 198 199### Display Options 200 201<dl> 202<dt class="option-term" id="option-cargo-doc--v"><a class="option-anchor" href="#option-cargo-doc--v"></a><code>-v</code></dt> 203<dt class="option-term" id="option-cargo-doc---verbose"><a class="option-anchor" href="#option-cargo-doc---verbose"></a><code>--verbose</code></dt> 204<dd class="option-desc">Use verbose output. May be specified twice for "very verbose" output which 205includes extra output such as dependency warnings and build script output. 206May also be specified with the <code>term.verbose</code> 207<a href="../reference/config.html">config value</a>.</dd> 208 209 210<dt class="option-term" id="option-cargo-doc--q"><a class="option-anchor" href="#option-cargo-doc--q"></a><code>-q</code></dt> 211<dt class="option-term" id="option-cargo-doc---quiet"><a class="option-anchor" href="#option-cargo-doc---quiet"></a><code>--quiet</code></dt> 212<dd class="option-desc">No output printed to stdout.</dd> 213 214 215<dt class="option-term" id="option-cargo-doc---color"><a class="option-anchor" href="#option-cargo-doc---color"></a><code>--color</code> <em>when</em></dt> 216<dd class="option-desc">Control when colored output is used. Valid values:</p> 217<ul> 218<li><code>auto</code> (default): Automatically detect if color support is available on the 219terminal.</li> 220<li><code>always</code>: Always display colors.</li> 221<li><code>never</code>: Never display colors.</li> 222</ul> 223<p>May also be specified with the <code>term.color</code> 224<a href="../reference/config.html">config value</a>.</dd> 225 226 227 228<dt class="option-term" id="option-cargo-doc---message-format"><a class="option-anchor" href="#option-cargo-doc---message-format"></a><code>--message-format</code> <em>fmt</em></dt> 229<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times 230and consists of comma-separated values. Valid values:</p> 231<ul> 232<li><code>human</code> (default): Display in a human-readable text format. Conflicts with 233<code>short</code> and <code>json</code>.</li> 234<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> 235and <code>json</code>.</li> 236<li><code>json</code>: Emit JSON messages to stdout. See 237<a href="../reference/external-tools.html#json-messages">the reference</a> 238for more details. Conflicts with <code>human</code> and <code>short</code>.</li> 239<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains 240the "short" rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> 241<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages 242contains embedded ANSI color codes for respecting rustc's default color 243scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> 244<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics in 245in JSON messages printed, but instead Cargo itself should render the 246JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others 247coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> 248</ul></dd> 249 250 251</dl> 252 253### Manifest Options 254 255<dl> 256<dt class="option-term" id="option-cargo-doc---manifest-path"><a class="option-anchor" href="#option-cargo-doc---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> 257<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the 258<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> 259 260 261 262<dt class="option-term" id="option-cargo-doc---frozen"><a class="option-anchor" href="#option-cargo-doc---frozen"></a><code>--frozen</code></dt> 263<dt class="option-term" id="option-cargo-doc---locked"><a class="option-anchor" href="#option-cargo-doc---locked"></a><code>--locked</code></dt> 264<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is 265up-to-date. If the lock file is missing, or it needs to be updated, Cargo will 266exit with an error. The <code>--frozen</code> flag also prevents Cargo from 267attempting to access the network to determine if it is out-of-date.</p> 268<p>These may be used in environments where you want to assert that the 269<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network 270access.</dd> 271 272 273<dt class="option-term" id="option-cargo-doc---offline"><a class="option-anchor" href="#option-cargo-doc---offline"></a><code>--offline</code></dt> 274<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this 275flag, Cargo will stop with an error if it needs to access the network and 276the network is not available. With this flag, Cargo will attempt to 277proceed without the network if possible.</p> 278<p>Beware that this may result in different dependency resolution than online 279mode. Cargo will restrict itself to crates that are downloaded locally, even 280if there might be a newer version as indicated in the local copy of the index. 281See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going 282offline.</p> 283<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> 284 285 286</dl> 287 288### Common Options 289 290<dl> 291 292<dt class="option-term" id="option-cargo-doc-+toolchain"><a class="option-anchor" href="#option-cargo-doc-+toolchain"></a><code>+</code><em>toolchain</em></dt> 293<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> 294begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such 295as <code>+stable</code> or <code>+nightly</code>). 296See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> 297for more information about how toolchain overrides work.</dd> 298 299 300<dt class="option-term" id="option-cargo-doc--h"><a class="option-anchor" href="#option-cargo-doc--h"></a><code>-h</code></dt> 301<dt class="option-term" id="option-cargo-doc---help"><a class="option-anchor" href="#option-cargo-doc---help"></a><code>--help</code></dt> 302<dd class="option-desc">Prints help information.</dd> 303 304 305<dt class="option-term" id="option-cargo-doc--Z"><a class="option-anchor" href="#option-cargo-doc--Z"></a><code>-Z</code> <em>flag</em></dt> 306<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> 307 308 309</dl> 310 311 312### Miscellaneous Options 313 314<dl> 315<dt class="option-term" id="option-cargo-doc--j"><a class="option-anchor" href="#option-cargo-doc--j"></a><code>-j</code> <em>N</em></dt> 316<dt class="option-term" id="option-cargo-doc---jobs"><a class="option-anchor" href="#option-cargo-doc---jobs"></a><code>--jobs</code> <em>N</em></dt> 317<dd class="option-desc">Number of parallel jobs to run. May also be specified with the 318<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to 319the number of CPUs.</dd> 320 321 322</dl> 323 324## ENVIRONMENT 325 326See [the reference](../reference/environment-variables.html) for 327details on environment variables that Cargo reads. 328 329 330## EXIT STATUS 331 332* `0`: Cargo succeeded. 333* `101`: Cargo failed to complete. 334 335 336## EXAMPLES 337 3381. Build the local package documentation and its dependencies and output to 339 `target/doc`. 340 341 cargo doc 342 343## SEE ALSO 344[cargo(1)](cargo.html), [cargo-rustdoc(1)](cargo-rustdoc.html), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) 345