cargo-readme
cargo-readme copied to clipboard
webern
Better handling of relative links
tsunami has a crate-local link (for a builder struct) in its top-level docs. While this works fine in generated documentation, that link is wrong when used in README.md. It'd be great if relative links could be removed in the generated readme, or if they could be made absolute relative to, say, docs.rs!
Sorry for taking too long to reply.
Unfortunatelly, that link location is way too specific of rust doc and would required cargo-readme to do a lot more than it does today to properly handle that.
If you know a better way to parse the doc strings and handle the link information, please let me know.
Hmm, that's unfortunate, but it also makes sense. I feel like this will only become more common as people start taking advantage of RFC 1946. It's really handy to use this short-hand for documenting types and methods, and it'd be a shame if those links are then all broken in GitHub READMEs :/ I guess the ultimate solution would be to parse Cargo.toml and create rustdoc-relative URLs relative to the documentation value, but even that will be error prone. I don't really have a solution to this, I just wish the simplest case of docs.rs + shortlinks + cargo readme would work :)
I've got a workaround hacking this together with a shell script, it just makes links that look like [`name`] into plain `name`.
https://github.com/porglezomp/pixel-canvas/blob/develop/gen-readme.sh
How about using comrak to parse the markdown and drop and relative links coming from rustdoc? (As a second step, one could make them absolute links with the correct base.) It seems their readme example could be modified to do this and then output with format_commonmark (instead of format_html currently there).
While possible, I don't think doing this as a post-processing step is as nice. The template file would also have its relative links stripped in this case (e.g. to files like the license or the code of conduct).
I understand that parsing links as RFC 1946 won't be too easy, but how about just adding a command-line flag or similar that gets appended to every relative link? This way I could use GitHub/GitLab pages or similar tools to publish my documentation, and have cargo-readme prepend https://msrd0.gitlab.io/project-name/crate_name to all relative links, making them correct links immediately. Having them point to files in the git tree really makes no sense, however, this is what GitHub/GitLab render relative links as of right now.
A really awful hack to do this is to include_str! the documentation in lib.rs, run rustdoc on it, then parse out the generated links :upside_down_face: https://github.com/rust-lang/rust/pull/75114 would help with this I think.
