From c9d444e8e08421e64f32500091567f63928f6f78 Mon Sep 17 00:00:00 2001 From: Hayden Stainsby Date: Wed, 24 Aug 2022 13:33:23 +0200 Subject: [PATCH] doc: correct `cargo doc` command in contrib guide (#4933) 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. --- CONTRIBUTING.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d324fd73f..a3c1c9108 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -154,7 +154,7 @@ 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 @@ -162,15 +162,9 @@ 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: