Update CONTRIBUTING.md with recommended commands for building docs #6475
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mox692
added
the
A-readme
joshka
reviewed
Apr 11, 2024
|
|
||
| ``` | ||
| RUSTDOCFLAGS="--cfg docsrs --cfg tokio_unstable" RUSTFLAGS="--cfg docsrs --cfg tokio_unstable" cargo +nightly doc --all-features | ||
| cargo install cargo-docs-rs |
There was a problem hiding this comment.
Should this be cargo install cargo-docs-rs --locked? (Saving users from install pain caused by any upstream dependency problems).
There was a problem hiding this comment.
could use cargo binsrall cargo-docs-rs to avoid cost of building the dep.
There was a problem hiding this comment.
I think --locked is a good idea, but I think we should not assume that developers are installing binstall.
There was a problem hiding this comment.
Yeah. Anyone that has installed binstall would know just use binstall generally, it's the newer users that often don't know to use --locked that can cause a support burden.
There was a problem hiding this comment.
I'm happy to accept a PR that adds --locked to the command.
joshka
referenced
this pull request
in joshka/tokio
Apr 12, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
As discussed in #6469.
Solution
--cfg tokio_unstable, as proposed by @Darksonn in the link above.--open, as this is most often what one would want. I am interested in feedback whether surrounding this flag in square brackets is self-explanatory enough to indicate that this flag is optional, or if we should just show it without the brackets, or entirely remove--open, or mention it in prose only.cargo +nightly docs-rswith a brief explanation. It is more memorable than the RUSTDOCFLAGS way, and applicable to repos outside of Tokio too.