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 ***@***.***> 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 <#45726 (comment)>, 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 😄

[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).

[jyn514]

This now has an rfc (which hasn't yet been accepted): rust-lang/rfcs#3081