Document mdBook playpen attributes

[projektir]

There does not appear to be documentation for the various playpen attributes in the UserGuide. I.e.:

• editable
• ignore
• mdbook-runnable

[uint]

Looks like editable is already documented by now.

Correct me where I'm wrong! As far as I can understand, ignore and noplaypen do the exact same thing and remove the run button. mdbook-runnable overwrites both and makes the thing runnable again, though I'm not sure what use case that would have?

The logic I found for this is in the specific renderers. Is there more that I've missed?

[ehuss]

There is a subtle distinction from ignore and noplaypen where noplaypen blocks will still be tested. It might be good to include the rustdoc attrs since they are relevant to how things work. And some examples would be good, too.

• editable — Allows a code block to be editable, requires output.html.playpen.editable=true in config.
• noplaypen — Will not show playground link, but will be tested. (Need to also specify rust.)
• mdbook-runnable — Forces the playground link to be shown. This is intended to be combined with the ignore attr for examples that you don't want to test, but want to allow the reader to run.
• ignore — Skips Rust tests, will not show playground link.
• should_panic — Rust code should panic when run. Shows playground link.
• no_run — Rust code should build, but not be run during a test. Shows playground link.
• compile_fail — Rust code should fail to compile. Shows playground link.
• edition2015 or edition2018 — Specifies the Rust edition.

UPDATE: See #1249 where some of these have changed.

[ISSOtm]

UPDATE: See #1249 where some of these have changed.

The PR ID looks wrong, I'm not sure which changes this is mentioning. Otherwise, I'd be ready to tackle this.

In the meantime, could the OP be updated with a task list of the attributes that need to be documented?

[ehuss]

I think #1249 is correct. no_run was changed so that it does not show the playground "play" button. I'm not sure if that changed any of the others (offhand I don't think it did, but it would be good to verify).

The list in #602 (comment) should be mostly complete with one change that noplayground has been renamed noplaypen. It might also be nice to link to the rustdoc docs here.

Otherwise, it would be good to verify the behavior of the list in #602 (comment), and a PR would be very appreciated!

[danielparks]

Clarification for future people who stumble upon this: “playpen” is now ”playground,” not the other way around (see #1241). In other words, use noplayground if you want to disable the play link.

(Sorry for the noise. Apparently GitHub thinks you need to know every time I push a change to a commit.)