Skip to content

Commit

Permalink
doc: correct cargo doc command in contrib guide (#4933)
Browse files Browse the repository at this point in the history
The command to build the documentation locally provided in the
Contribution Guide did not work for all crates in the project workspace.
Specifically, to build the docs for `tokio-stream` the flag `--cfg
docsrs` needs to be in the environment variable `RUSTFLAGS` in addition
to being in `RUSTDOCFLAGS`.

Additionally, there was text describing that the docs cannot be built
from the root of the workspace with a link to rust-lang/cargo#9274. That
issue has since been closed as complete and the listed commands do now
work from the root of the workspace. As such, that text has been
removed.
  • Loading branch information
hds authored Aug 24, 2022
1 parent e005b6c commit c9d444e
Showing 1 changed file with 2 additions and 8 deletions.
10 changes: 2 additions & 8 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,23 +154,17 @@ required for various parts of Tokio are missing. To build the documentation
correctly, use this command:

```
RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
RUSTDOCFLAGS="--cfg docsrs" RUSTFLAGS="--cfg docsrs" cargo +nightly doc --all-features
```

To build documentation including Tokio's unstable features, it is necessary to
pass `--cfg tokio_unstable` to both RustDoc *and* rustc. To build the
documentation for unstable features, use this command:

```
RUSTDOCFLAGS="--cfg docsrs --cfg tokio_unstable" RUSTFLAGS="--cfg tokio_unstable" cargo +nightly doc --all-features
RUSTDOCFLAGS="--cfg docsrs --cfg tokio_unstable" RUSTFLAGS="--cfg docsrs --cfg tokio_unstable" cargo +nightly doc --all-features
```

There is currently a [bug in cargo] that means documentation cannot be built
from the root of the workspace. If you `cd` into the `tokio` subdirectory the
command shown above will work.

[bug in cargo]: https://github.com/rust-lang/cargo/issues/9274

The `cargo fmt` command does not work on the Tokio codebase. You can use the
command below instead:

Expand Down

0 comments on commit c9d444e

Please sign in to comment.