New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
rustdoc: literate rust #26097
Comments
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. |
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 |
There has not. I wonder if it would take an RFC these days, since it would be a pretty major change. |
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. |
This looks promising: https://github.com/pnkfelix/tango |
Triage: |
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.
The text was updated successfully, but these errors were encountered: