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.
6 Likes
However the crux of my dislike is more about the experience as a developer when reading code. External docs optimize for the writer (because tooling that just deals in markdown is easy to write) over the reader (of which there will be many now and in the future).
Regarding the caveats of cargo-readme - it doesn't handle the discrepancy between what rust doc supports and what README supports - specifically hiding rust code lines. That's why you see leading # on various lines of sample code in downcast-rs documentation, which would ideally be eliminated. Similarly it significantly misbehaves if you ad conditional documentation via #doc(...) (which I originally misconstrued as a bug in crates.io markdown support, but crates.io README is intended to match github's markdown support, not rustdoc's.
I found a workaround for the latter, but I've been busy, so I've not yet investigated a solution to the former unfortunately.