Best practice to manage links in READMEs

1

I'm sure this is a problem a lot of people have, but I could not find any clear suggestion of a best practice.

Often you have a README.md that is included as documentation in lib.rs. This means that the links in the file must work both withn reading the README.md on Github, and when it is included in the documentation.

The only solution I found up to know is to link directly to docs.rs, as in

[`MemCase`]: https://docs.rs/epserde/latest/epserde/deser/mem_case/struct.MemCase.html

The problem is that now locally-generated documentation will point to possibly older documentation in docs.rs.

What are you guys doing? I've seen projects with two identical copy of the package documentation, one in lib.rs and one in README.md, with local and non-local links, respectively, but it does not seem a good practice.

2

You can host the rustdoc built from main or dev branch on github, and use links to that doc in README, then all API links are newest.

rand crate is one of the examples. https://github.com/rust-random/rand/deployments/github-pages

FYI despite of the self-hosted doc by rand, links for APIs in its README still points to docs.rs.

1155×380 43.8 KB

3

I thought about that, and it's certainly a possible solution, but it really feels like a waste of space.

4

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.