Fix external doc builds #86
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
The latest rust nightlies and beta (at stable version 1.55) include a
change from
#![cfg_attr(feature = "nightly", feature(external_doc))]
#![cfg_attr(feature = "nightly", doc(include = "../README.md"))]
to removing `feature(external_doc)` and also changing the syntax of
the second line to
#![cfg_attr(feature = "nightly", doc = include_str!("../README.md"))]
However. `include_str!` is stable currently, but the syntax of `doc =
` is expressly disallowed. This gives me four options:
1. Don't build documentation (bad)
2. Copy-pasta README.md into src/lib.rs (also bad)
3. Support only beta/nightly but not stable (completely untennable
for a crate with ~14 million downloads)
4. Support only stable but not beta/nightly (also untennable)
Further, waiting for this to be "fixed" by its inclusion in stable
Rust in about a week means that our MSRV increases from 1.41 to 1.56,
with no changes to actual code (other than how to build documentation)
at all, which seems quite unfriendly to downstream dependents who are
pinning their rust versions for whatever reason.
So, sadly, it seems the most friendly fix is to copy-pasta our
README.md into the codebase.
(cf. rust-lang/rust#44732,
rust-lang/rust#82539)
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.
The latest rust nightlies and beta (at stable version 1.55) include a
change from
to removing
feature(external_doc)and also changing the syntax ofthe second line to
However.
include_str!is stable currently, but the syntax ofdoc =is expressly disallowed. This gives me four options:for a crate with ~14 million downloads)
Further, waiting for this to be "fixed" by its inclusion in stable
Rust in about a week means that our MSRV increases from 1.41 to 1.56,
with no changes to actual code (other than how to build documentation)
at all, which seems quite unfriendly to downstream dependents who are
pinning their rust versions for whatever reason.
So, sadly, it seems the most friendly fix is to copy-pasta our
README.md into the codebase.
(cf. rust-lang/rust#44732,
rust-lang/rust#82539)