Skip to content

Commit

Permalink
readme: mention cargo-docs-rs in CONTRIBUTING.md (tokio-rs#6475)
Browse files Browse the repository at this point in the history
  • Loading branch information
dtolnay authored Apr 11, 2024
1 parent 224fea4 commit 43de364
Showing 1 changed file with 16 additions and 8 deletions.
24 changes: 16 additions & 8 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,20 +152,28 @@ When updating this, also update:
cargo +1.77 clippy --all --tests --all-features
```

When building documentation normally, the markers that list the features
required for various parts of Tokio are missing. To build the documentation
correctly, use this command:
When building documentation, a simple `cargo doc` is not sufficient. To produce
documentation equivalent to what will be produced in docs.rs's builds of Tokio's
docs, please use:

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

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:
This turns on indicators to display the Cargo features required for
conditionally compiled APIs in Tokio, and it enables documentation of unstable
Tokio features. Notice that it is necessary to pass cfg flags to both RustDoc
*and* rustc.

There is a more concise way to build docs.rs-equivalent docs by using [`cargo
docs-rs`], which reads the above documentation flags out of Tokio's Cargo.toml
as docs.rs itself does.

[`cargo docs-rs`]: https://github.com/dtolnay/cargo-docs-rs

```
RUSTDOCFLAGS="--cfg docsrs --cfg tokio_unstable" RUSTFLAGS="--cfg docsrs --cfg tokio_unstable" cargo +nightly doc --all-features
cargo install cargo-docs-rs
cargo +nightly docs-rs [--open]
```

The `cargo fmt` command does not work on the Tokio codebase. You can use the
Expand Down

0 comments on commit 43de364

Please sign in to comment.