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...
The docs are written as strings in a special tests directory, with special markup to mark code that is not included in the output, and special code for generating (at test-time) and creating inline iframes for results where applicable.
Code examples in docs that aren't executed will very often be wrong. That's just a fact of life. So we execute them all.