Document items behind feature flags #103
Merged
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
Use the unstable feature doc_auto_cfg to document items' feature flags, and configure docs.rs runs to compile all features. For now, using this locally requires running `cargo +nightly rustdoc --all-features -- --cfg docsrs`.
jeff-hiner
approved these changes
Oct 10, 2022
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.
Should cause
docs.rsto build documentation for items behind feature flags, and to label them with the associated feature flags.Uses the
--all-featurescargo option and the unstabledoc_auto_cfgfeature to achieve this. Places thedoc_auto_cfgfeature behind a cfg flag so that it's only used when running ondocs.rs.Includes a plan accounting for the (currently) expected stabilization path for
doc_auto_cfg.Unfortunately, I lack the setup required to run
docs.rslocally, so I cannot test thedocs.rs-specific configuration options at this time. I understand that may make this PR not very useful. For what it's worth, the configuration options are based on those used bytokio.Sorry about the lack of testing; I just thought this was an interesting problem, went and read about it, and am offering this code containing what I learned, in case it is of any use.
Under this PR, docs can be built locally with
cargo docas usual, but observing the new features requires instead usingcargo +nightly rustdoc --all-features -- --cfg docsrs.Stable alternatives include just running
cargo docwith--all-features; however, the docs produced this way do not indicate which items require feature flags.Closes #102.