Use doc_auto_cfg to show feature requirements on docs.rs #487
Conversation
This file contains hidden or 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
Add a `docsrs` config in the `docs.rs` metadata in Cargo.toml. This will set `--cfg docsrs` when building on docs.rs. Enable the `doc_auto_cfg` feature when the `docsrs` config is enabled. This feature is currently unstable, but docs.rs uses a nightly compiler so this works fine. The effect of this is that docs.rs will show a badge for items that are only available if some feature is enabled. For example, `BootServices::find_handles` will have a badge saying "Available on crate feature exts only." To view this locally, run this: ``` RUSTDOCFLAGS="--cfg=docsrs" cargo +nightly doc --all-features --open ``` This change has only been applied to the `uefi` package, since the `uefi-macros` package does not have any features and the `uefi-services` package's features don't control the visiblity of any public items. rust-osdev#486
|
Merging since I want to include this in #488. Low-risk change since it should only affect anything on docs.rs. |
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.
Add a
docsrsconfig in thedocs.rsmetadata in Cargo.toml. This willset
--cfg docsrswhen building on docs.rs. Enable thedoc_auto_cfgfeature when the
docsrsconfig is enabled. This feature is currentlyunstable, but docs.rs uses a nightly compiler so this works fine.
The effect of this is that docs.rs will show a badge for items that are
only available if some feature is enabled. For example,
BootServices::find_handleswill have a badge saying "Available oncrate feature exts only."
To view this locally, run this:
This change has only been applied to the
uefipackage, since theuefi-macrospackage does not have any features and theuefi-servicespackage's features don't control the visiblity of any public items.
#486