Please add support for generating markdown files from rust documentation comments. By generating markdown files, we can easily add these files to our github projects as the documentation of the project and these markdown files are simple in syntax and can be read on github within the browser like any other README.md file is for any github repo.
Typically people go the other way around: type your documentation in markdown files and import it into docs:
#[doc = include_str!("something.md")]
struct Item {
8 Likes
A major thing that this misses is cross-links between documentation pages. That and any hidden lines in code blocks not being hidden.
But it is a reasonable enough solution imo, and it doesn't require tracking generated files in the version control.
2 Likes
I really dislike this practice. It's a pain when you're interested in the docs of some library that you use. It doesn't show up in the hover docs of VSCode, and effectively adds an annoying extra disconnected step when reading the source code of some library via the goto definition action.
I'd strongly encourage going this way around (generate markdown from source) rather than including markdown in doc comments because of this.
Cargo-rdme is pretty good at doing lib.rs -> README.md (there are some caveats). From an implementation perspective, I'd start there.
If rust-analyzer doesn't handle this, then rust-analyzer should be fixed.
3 Likes