Only enable vergen on docsrs #533
Conversation
| @@ -59,6 +59,9 @@ regex = ["dep:regex-automata"] | |||
| # Enable serde serialization support | |||
| serde = ["dep:serde"] | |||
|
|
|||
| # Enable dependencies only needed for generation of documentation on docs.rs | |||
| docsrs = ["dep:vergen"] | |||
There was a problem hiding this comment.
Have you checked that this actually gets enabled with generating docsrs docs?
There was a problem hiding this comment.
I haven't tested it with the live docsrs, since I'm not sure how one would go about doing so.
My understanding is that the docsrs feature gets enabled by
Lines 67 to 69 in af4e2b1
There was a problem hiding this comment.
I don't think this would enable such a feature. The cfg flag just allows you to do #[cfg(docsrs)] (which would probably be sufficient for your purposes, fwiw, instead of adding a cargo feature).
There was a problem hiding this comment.
Okay, I tried a few things in that direction, but haven't quite managed to get it to work as expected.
So I first tested the code with RUSTFLAGS="--cfg docsrs" cargo doc --open. (Because someone said that it's a workaround of some sort.) That only seems to pass the info to the Cargo.toml part. It doesn't pass the info to the lib.rs file, since #[cfg(docsrs)] in lib.rs had no effect.
Then I tested it with cargo rustdoc --open -- --cfg docsrs. This lets me do #[cfg(docsrs)] in lib.rs, but does not pass it to the build.rs script. And importantly, it doesn't seem to let me make vergen an optional feature.
I could probably find a variation where I get it to work, but it might almost be easier to make the docsrs stuff a feature. all-features = true should turn on the docsrs feature. Unless of course, you've got a good idea. I'm definitely willing to try out more stuff.
There was a problem hiding this comment.
Have you tried the command at the top of guide.rs?
RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
There was a problem hiding this comment.
I missed that command, thank you.
So I tested it just now:
Conditionally compiling vergen does not seem to be possible with
[target.'cfg(docsrs)'.build-dependencies]
vergen = { version = "=8.1.1", features = ["git", "gitoxide"] }
Conditionally compiling it with --all-features and then docsrs = ["dep:vergen"] does seem to work.
There was a problem hiding this comment.
Hmm, not sure I understood this message. So this does work?
There was a problem hiding this comment.
Yep, this pull request should work.
|
Thanks for the PR! |
|
I'm assuming that the new version on crates.io includes this PR? The links seem to be broken now, they point at https://docs.rs/chumsky/1.0.0-alpha.5/chumsky/index.html#example-brainfuck-parser |
|
It doesn't include this PR, the new version was released yesterday. |
|
@zesterer I see. So was the vergen approach always doomed to fail on docs.rs? Or does that call for some tricky investigation? |
Hopefully fixes #503
I personally would prefer if rustdoc fully supported including example code in the documentation, but this is better than nothing for now.