rustdoc: add cli argument --playground-url
#37763
Conversation
|
(rust_highfive has picked a reviewer for you, use r? to override) |
|
Seems like a reasonable feature to me. |
|
@bors: r+ |
|
📌 Commit dc3859d has been approved by |
ollie27
left a comment
ollie27
left a comment
There was a problem hiding this comment.
Do we really need two command line options which do the same thing for Markdown rendering?
I can envision having a --html-playground-url as an alternative to #![doc(html_playground_url)] but it's not clear to me what should happen if both are set. What's proposed here is one option but for the use case of websites like docs.rs surely you would want to override whatever was set by #![doc(html_playground_url)].
Shouldn't we be a bit more careful before adding new stable command line options to rustdoc?
Either way this could do with tests.
| }; | ||
|
|
||
| if let Some(playground) = matches.opt_str("playground-url") { | ||
| html::markdown::PLAYGROUND.with(|s| { *s.borrow_mut() = Some((None, playground)); }); |
There was a problem hiding this comment.
When doing HTML rendering the crate name needs to be set so the correct extern crate can be added to the code. The first item in the tuple is the crate name.
There was a problem hiding this comment.
will do that in follow up PR, thanks @ollie27 !
existing
That'd be a breaking change? |
|
⌛ Testing commit dc3859d with merge 01d061f... |
rustdoc: add cli argument `--playground-url` Add a new cli argument `--playground-url` for rustdoc: `rustdoc lib.rs --playground-url="https://play.rust-lang.org/"` `rustdoc book.md --playground-url="https://play.rust-lang.org/"` This makes it possible for tools like https://docs.rs to generate crate docs that can submit samples code to run at https://play.rust-lang.org, even if the crate's author *forgot* putting `#![doc(html_playground_url = "https://play.rust-lang.org/")]` to crate root. By the way, I'd like to say, many crate authors are not aware of existing of `#![doc(html_playground_url = "https://play.rust-lang.org/")]`. `--playground-url` may be reset by `--markdown-playground-url` or `#![doc(html_playground_url=...)]`, so it's backward compatible. @alexcrichton since you implemented playground-url related features.
rustdoc: get back missing crate-name when --playground-url is used follow up PR #37763 r? @alexcrichton (since you r+ed to #37763 ) ---- Edit: When `#![doc(html_playground_url="")]` is used, the current crate name is saved to `PLAYGROUND`, so rustdoc may generate `extern crate NAME;` into code snips automatically. But when `--playground-url` was introduced in PR #37763, I forgot saving crate name to `PLAYGROUND`. This PR fix that. ---- Update: - add test - unstable `--playground-url`
7 participants
Add a new cli argument
--playground-urlfor rustdoc:rustdoc lib.rs --playground-url "https://play.rust-lang.org/"rustdoc book.md --playground-url "https://play.rust-lang.org/"This makes it possible for tools like https://docs.rs to generate crate docs that can submit samples code to run at https://play.rust-lang.org, even if the crate's author forgot putting
#![doc(html_playground_url = "https://play.rust-lang.org/")]to crate root. By the way, I'd like to say, many crate authors are not aware of existing of#![doc(html_playground_url = "https://play.rust-lang.org/")].--playground-urlmay be reset by--markdown-playground-urlor#![doc(html_playground_url=...)], so it's backward compatible.@alexcrichton since you implemented playground-url related features.