rustdoc: literate rust

[RalfJung]

It would be nice if rustdoc (or rustbook? Not sure which of the two fits better) could generate "annotated source" output: Given a Rust file, generate an HTML file with the source code in proper syntax highlighting, and with the comments interpreted and rendered as markdown. That would make it possible to write executable Rust code that is at the same time a readable document (for example, a tutorial). The result could be similar to Docco.

[steveklabnik]

Yes, this would be neat. We mostly try to keep feature requests on the RFCs repo, but have gotten lax about it, so I'm just going to leave this here for now.

[calebmer]

Has there been any update on this? I'm writing a trait which has a lot of functionality which can't be defined in the type system (not a problem with the rust type system, just my use case). So along with the trait I'm writing a test suite.

I'd like the test suite to be written in literate rust and have the rendered document be considered a “specification” for trait implementors.

Even if this is not a high priority feature, is there any preference/speculation on what the syntax would be so I could at least annotate my code even if the renderer isn't present yet? I was thinking about using comment strings prefixed with //*.

[steveklabnik]

There has not. I wonder if it would take an RFC these days, since it would be a pretty major change.

[steveklabnik]

Worth noting that rustdoc can already run over raw markdown files, with embedded code blocks. This isn't a true literate mode, but it does help when writing documentation, and can feel like literate code at times.

[killercup]

This looks promising: https://github.com/pnkfelix/tango

[steveklabnik]

Triage: tango has you covered, and I don't believe this is going to land in upstream rustdoc any time soon. Closing!