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.
1 Like
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 {
10 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.
3 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.
11 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.
I was just working on the same thing because I didn't want to keep switching between my editor and browser. I couldn't find any ongoing work on markdown support in rustdoc, the workaround that I came up with uses rustdoc json (rustdoc_types) to generate per module markdown files. It generates local markdown docs for a project and all its dependencies, with:
- One file per module (mirrors rustdoc's structure)
- Cross-crate/module reference links that work in github/editors
The cross-reference links between modules and crates work on github - you can jump between docs from one crate to another by clicking on the links. The link resolution needs more work to be honest.
If anyone wants to try it or has feedback on link resolution, I'd appreciate it. I couldn't find anyone else who was interested in markdowns 
Here's the repo: docs-md (generated docs are in generated_docs/)
Sorry if this isn't the right thread, it's the closest discussion I could find on this topic.