Literate doctests

b126742
Opened by Alex Burka at 2021-03-08 14:45:57

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

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

    Steve Klabnik at 2017-11-02 20:04:29

  2. 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.

    QuietMisdreavus at 2017-11-02 20:05:15

  3. cc @pnkfelix

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

    Manish Goregaokar at 2017-11-02 20:29:44

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

    On Thu, Nov 2, 2017 at 4:30 PM, Manish Goregaokar notifications@github.com 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 .

    Alex Burka at 2017-11-03 13:45:28

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

    Steve Klabnik at 2017-11-03 14:01:19

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

    Jane Losare-Lusby at 2020-04-12 03:11:18

  7. 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:

    Pascal Hertleif at 2020-04-14 16:07:58

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

    Jane Losare-Lusby at 2020-04-14 19:53:08

  9. @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).

    Guillaume Gomez at 2020-04-22 19:45:51

  10. This now has an rfc (which hasn't yet been accepted): https://github.com/rust-lang/rfcs/pull/3081

    jyn at 2021-03-08 14:45:57