[BUG] broken links on landing page for docs.rs zkvm crate

[pdg744]

[BUG] broken links on landing page for docs.rs zkvm crate

[tzerrell]

Additional context:

• This also fails on crates.io/crates/risc0-zkvm and also fails for the verify link
• This seems to be because Rust intra-doc links are either not supported or not fully supported by crates.io and by docs.rs/crates (they do seem to be supported by the general docs.rs documentation).

I think this gives a few options:

• Remove intra-doc links from the crate summaries
  • We could just remove the links and not replace them
  • We could replace the intra-doc links with HTML links (e.g. https://docs.rs/risc0-zkvm/latest/risc0_zkvm/struct.Receipt.html); this loses the benefits of intra-doc links in the docs.rs and cargo doc cases though.
• Allow the links to be broken on docs.rs/crate and crates.io
• Investigate alternative ways to use intra-doc links that work on crates.io and docs.rs/crate
  • Unclear if any solutions exist

[flaub]

This appears to be related: hadronized/cargo-sync-readme#11

[flaub]

I'm trending towards just having these links be broken on crates.io. But I'd like to see what other prominent projects do to deal with this issue as one last bit of effort on this.

[flaub]

I might have found a tool that can address this issue: https://github.com/orium/cargo-rdme

It looks like the way this works is that we'd have normal rust docs in .rs files. Then we'd run cargo rdme to generate the README file, which does the translations to deal with links.

[flaub]

Or this tool: https://github.com/phaazon/cargo-sync-readme