Rust: Literate doctests

[durka]

This might be RFC-worthy.

What if you could tie several sequential doctests together so that they operate as a single code block, but you can still write narrative comments in between in a literal style? This could cut down on ignore/no_run code blocks as well as hidden lines at the same time.

Example

Here is an example of using mutable variables. First, let's make some bindings.

```rust
let a = 1;
let mut b = 2;
```

`a` can't be modified, but `b` can!

```rust,cont
// a += 1; // this would be an error!
b += 1;
```

Clicking the run button on either code block would open a playpen with all the code. Syntax up for debate.

cc @QuietMisdreavus

[steveklabnik]

Yeah, this seems neat, but definately needs an RFC IMHO.

[QuietMisdreavus]

cc @rust-lang/docs @rust-lang/dev-tools - would adding a new flag to doctests for this behavior require an rfc, or can we just get away with making it unstable to begin with (like compile_fail was, and the error number callouts still are)?

I can get behind this, regardless, though it may require changing the sample the Rustdoc Book uses to demonstrate hidden lines.

[Manishearth]

cc @pnkfelix

I think experimentation within rustdoc doesn't require an RFC. Stabilization does.

[durka]

@steveklabnik does the new rustdoc cover doctests yet? Perhaps we should
experiment there.

On Thu, Nov 2, 2017 at 4:30 PM, Manish Goregaokar [e-mail]
wrote:

cc @pnkfelix https://github.com/pnkfelix

I think experimentation within rustdoc doesn't require an RFC.
Stabilization does.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/rust-lang/rust/issues/45726#issuecomment-341548385,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAC3n2trE6zReFLCBGm4f6qxyM76Ldz2ks5syiZYgaJpZM4QQQyU
.

[steveklabnik]

We haven't implemented any of that yet; we're working through RLS bugs to get the basics displaying at the moment.

[yaahc]

I'm interested in working on this, does it reaally really need an rfc?

[killercup]

Can't answer the RFC question but I think this is a really nice feature, especially if you plan on having guide-like content in your docs. I've literally written a tool to have that style in non-rustdoc context :smile:

[yaahc]

Okay I'm gonna go ahead with an impl then and deal with the RFC question when it becomes an issue!

[GuillaumeGomez]

@yaahc Good luck! Don't hesitate to ping me if you have questions (either on discord or twitter since we interacted a few times there).