search

webern / cargo-readme

Generate README.md from docstrings
Other
350 stars 57 forks source link

Support for intra-doc links #55

Open agausmann opened 3 years ago

agausmann commented 3 years ago

Intra-doc links allow documentation authors to link to items by their path relative to the current module. It would be nice to resolve intra-doc links in the same way that rustdoc does, and make them point to the documentation at docs.rs or wherever else the API documentation is hosted.

zbraniecki commented 3 years ago

It would be great to have an ability to customize the docs path (instead of hardcoding docs.rs) - we use live docs in a custom github pages location and would prefer to link our readme to that.

agausmann commented 3 years ago

or wherever else the API documentation is hosted.

Maybe via a command-line option, or it can read it from the Cargo.toml parameter. However I agree it would make more sense to link to docs generated from the latest commit, if they are available, instead of the docs URL in the manifest.

zicklag commented 3 years ago

An option to remove the intra-doc links would be a decent middle-ground, so that I don't have a bunch of broken API docs links in my README, but to do that accurately would require parsing the markdown as markdown instead of the simple line-based processing procedure taken currently, due to the existence of the reference-style markdown links.

LPGhatguy commented 2 years ago

I figured out a pretty easy workaround. Stick a Markdown reference-style link in your template for all the types you refer to. This lets you refer to a specific docs.rs version or even the latest.

Here's how I did this for thunderdome: https://github.com/LPGhatguy/thunderdome/blob/21606a1172521772dfae79d9a247e6ab12a641b0/README.tpl#L5-L6

orium commented 2 years ago

cargo-rdme implements README generation and replaces intralinks with links to docs.rs: https://github.com/orium/cargo-rdme#intralinks

Disclaimer: I'm the author of the crate :)

Manishearth commented 1 year ago

A way to make this more pleasant without requiring too much work would be to just strip out intra doc links.

Could also strip out # lines from rust code samples.

orium commented 1 year ago

Shameless plug: cargo-rdme not only generates intralinks to docs.rs, it also has a flag (or configuration file) to strip the intralinks if you so choose.

It also strips out the # in rust code. And it also tags the markdown code block as rust if that was not the case (even if it is just tagged as should_panic or no_run or all the other stuff rustdoc recognizes as rust code).