News for hackers. Stuff that matters.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by pie_flavor on Saturday November 05, 2022 @12:02AM (#33477807)
One of my favorite features about Rust: this is the default for all documentation comments, and thus for auto-generated API docs.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by boxed on Saturday November 05, 2022 @04:59PM (#33485669)
This documentation page: https://docs.iommi.rocks/en/latest/forms.html is generated from this pytest source: https://github.com/TriOptima/iommi/blob/master/docs/test_doc...

Is that how rust documentation works?

Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by pie_flavor on Saturday November 05, 2022 @06:18PM (#33486495)
The meaning is the same; the syntax is different. All triple-backtick codeblocks in doc comments, unless annotated 'ignore', are run as tests when you run `cargo test`. So from this file[0], this doc page[1] is generated. And there's more flexibility than 'run or ignore' too, e.g. one on that page is marked ```compile_fail,E0277 to fail the test if it compiles or has a different compilation error than expected. And then every code block known to be runnable has a Run button you can click to open the snippet in the Rust Playground.

These are API docs, but mdBook[2], which generates documentation that looks like this[3], has a test command which checks the code blocks the same way.

[0]: https://doc.rust-lang.org/stable/src/alloc/string.rs.html#76

[1]: https://doc.rust-lang.org/stable/std/string/struct.String.ht...

[2]: https://rust-lang.github.io/mdBook/

[3]: https://doc.rust-lang.org/book/