Today I wrote a blog-post about my own crate cellular_raza where I cited other's work by linking to the respective crates. But then I thought to myself: Why do I cite https://docs.rs and not https://crates.io or the link to their repositories? So this spawned the question in the title.
Observations (Variants)
If we create links with rustdoc i.e. // [serde_json] it will link to the appropriate version at docs.rs/serde_json.
However, I have also seen people who cite the crate at crates.io.
So my (very open) question is: Is there a de-facto way to link to a crate? How do you do it generally?
I am also interested since I am the author of crate2bib which provides simple BibLaTeX entries when given a crate name. It would be interesting to know which link one would expect in such a situation.
I am not an academic to comment on citation formats, but here are my thoughts on the various sorts of links, at least.
The advice I give people who are writing documentation about their library is:
The package README (which a crates.io link leads to) should explain when to use the library — what kinds of problems it can solve.
The library doc text (which a docs.rs link leads to) should explain how to use the library — how the items within the library relate to solving a problem of that kind.
This is only my own opinion and many published library packages don't follow this principle. Regardless, I generally use docs.rs links when recommending libraries, because implicitly I’m addressing the “when to use” part in my own post — but if I were doing something like talking about which dependencies my own project uses, I would write crates.io links instead, because it focuses more on the metadata of the package than the usage.
One of the most important parts of a link or a citation is that it doesn't break. crates.io offers a guarantee that for most purposes, a package will never be deleted regardless of its maintenance status or value. Even if the Rust project moved its package hosting to another domain name, which package gets which name in that namespace would not changed. Repository hosting sites generally do not offer any such guarantee — repositories are routinely deleted or moved to other addresses. Furthermore, projects large and small may move to different hosting entirely due to dissatisfaction with the prior host.
Therefore, a link, especially for citation purposes, should refer to crates.io, or something derived from the same package database like docs.rs, and not the repository, unless the thing being cited is actually an artifact of the development process occurring in that repository.
For a canonical URL of a crate, use crates.io/crate/$name. That's the site that has the authority over what the crate is.
Linking to docs.rs is fine too. There's a simple 1:1 mapping between crates.io and docs.rs. The docs link may save users a click if you're directing them to use the library.
These two options are IMHO way better than linking to a Github repo, since there's no guaranteed relationship between Github URLs and crates, so users would first need to figure out what is the correct crate name to use in Cargo.
And I'm biased, but I also like https://lib.rs/$name links for crates, since that's probably the shortest non-obfuscated URL you can get.
For crates developed from academia, the expected thing would be a DOI link to a relevant publication. I don’t think that’s stored in any standardized place, though.
Not each crate which might be used by academics has a corresponding publication
The crate authors are not actively pursuing this goal since their use-cases might not be academic and thus cite-count might not be their main focus of work.
That is precisely the reason, why I created crate2bib. It is able to find at least any Citation.cff files which are in the corresponding respository and then generate an entry from there. This is not identical to the DOI you were referring to but comes close.
Well, if you follow my principle, that’s true as a typical consequence of what kind of content should be found in each place, not as a rule in itself. For example, a if a readme had good reason to mention a specific item from another crate (e.g. "this crate provides a struct that is an adapter from ThisTrait to ThatTrait”), then there would be docs.rs links present in that readme.
(By the way, docs.rs does also host readmes (example); people just generally don't use it for that. Though, docs.rs (and lib.rs) are arguably superior to crates.io because they serve plain documents and do not require executing any JavaScript to view the content.)
I think it depends on your estimate of the site’s stability and relevance. Just because a project has a domain name doesn’t mean that it won’t be abandoned abruptly — either because the maintainer quits or because the maintainer thought of the site primarily as a piece of advertising, not reference material.
If I were writing standards for citations of software, which I am not, I would personally recommend including both a link to the most independently owned site (such as bevy.org in your example) and a link to the “biggest, most stable” site that has an appropriate page (which for Rust would be crates.io). These two things both may fail, but at different times for different reasons.
