adding docs.rs badge to crate sidebar #459
Conversation
|
I wonder what @briansmith thinks of this; he's one of the people who's very anti-docs.rs, at least at the moment. The reason I bring it up is, the idea for putting it in the text wasn't that we'd put the badge in the text, it's that if there was no documentation link, we'd put the current text with the link. This would let people opt out, which isn't really possible with the badge here. That said, if others are okay with it, I'm okay with it, I just want to make sure those concerns are addressed. |
|
Ah, yeah, I had an unless in there before to only show it if there wasn't documentation but I thought the badge looked funky below, but having it in two places conditionally would also be jarring. I didn't think to just use a docs rs link in the current docs link location because the badge looked slick. :) By opt out do you mean simply not using docs.rs or something more? |
|
Interesting, I'd like to know why @briansmith is against docs.rs |
I never said I was "against docs.rs". Clearly a lot of people like the docs.rs service and I think it's a good service, particularly for people who don't want to bother with hosting their documentation themselves. I'm also giving them the benefit of the doubt that they'll address the issues below. What I said is I'd prefer to direct people to my own published copy of the documentation. Why does the Rust team publish the libstd documentation at https://doc.rust-lang.org instead of relying on docs.rs? I think the reasons that the Rust teams have for maintaining https://doc.rust-lang.org are likely the same reasons as some people have for wanting to publish their crates' documentation themselves. Note that docs.rs doesn't show the documentation for my ring crate correctly; in particular, it is missing the |
I tried to phrase this as something that didn't imply @briansmith was against it in general, only that it isn't perfect and the way in which it isn't perfect is important to some people. I don't mean to put words in his mouth here, sorry if I was misleading in my wording.
Well, docs.rs is very new, and doc.rust-lang.org is very old. At least for the standard library documentation, putting on docs.rs would be a huge win, and I'd be in favor of it.
Let me make sure that there's an issue open about this, this is important. |
|
@briansmith, thanks for feedback. I thought you are against docs.rs when Steve referred you as "very anti-docs.rs". My bad sorry. Actually first thing Rust team asked me to host std docs when I first released docs.rs. Few other people also asked for it. You are right about onur/docs.rs#29 but I've been extremely busy since I released docs.rs and didn't have much time to work on it. I am back on project and hopefully will fix this issue really soon. |
I'm definitely not against docs.rs.
Probably this is a misunderstanding and I think it doesn't matter.
That would be great! I also commented on the license issue in your repo. Anyway, I don't want to distract from the actual review of the PR. |
|
Thanks for the PR @rjgoldsborough! In terms of the implementation I think we may also want to link to the right version of the documentation, so perhaps From the "if we'd like to have this" point of view I'm personally in favor but like @steveklabnik am also curious of others' opinions. @briansmith I'm curious, if this were added to crates.io would you prefer to opt-out of this link for your crates? |
I think it's better to link to the latest version like the "Documentation" link does in most cases.
The license for the documentation for my stuff allows people to republish it. I would prefer that docs.rs republish things in a better way and I'll work with them in their issue tracker regarding those improvements. However, I'm not sure about the next PR adding a different badge, and the one after that, and the ones after those. BTW, I'm not sure if you fully understand the privacy and business implications of these badges. If you add the badge on every crate then the service hosting the images in the |
|
BTW I want to mention onur/docs.rs#29 is getting fixed soon. And TBH I also think it is still early to add a docs.rs link to crates.io. I agree with @steveklabnik docs.rs is ok but far from perfect, there are some flaws, especially cross crate links don't work. Builds with non-default features are getting fixed soon. @alexcrichton is also right. Docs.rs currently cannot handle dead links properly, clippy for example, it's not a useful error message and might be really confusing for newcomers. Many people started using docs.rs for their documentation links and docs.rs badges in their README's. IMO lets leave it like that, crate owners can decide if they want to use docs.rs or not for their documentation source. And I will continue developing docs.rs and fix some serious flaws, like cross crate links, improved error handling and more automated way to build/publish docs. For the privacy, I can assure you docs.rs is not tracking anything. Docs.rs doesn't even have any goggle-analytics code unlike crates.io. I also deeply care about privacy and it's not none of my business who is visiting what crate or website. Anyway, I agree with @briansmith about badges. And depending on a third party service is not a good idea. If we really want to show badges in crates.io we can use my badge crate. It's been working fine on docs.rs for a while and much better than depending on a third party service. |
|
For reference, here are the four issues I think are important, as a crate author and privacy advocate:
BTW, as far as I can tell, they seem like 100% upstanding people who are just trying to provide a useful service. But you can imagine that somebody else could easily fork their code, wrap all the content in advertising and trackers on a new website, and then ask for equal treatment with their own tracker-ific badge. This is more what I'm trying to discourage. |
|
I personally think that at least one major blocker for this will be to not generate a link for crates which have documentation that failed to build on docs.rs. That may unfortunately provide a pretty sub-par experience :( |
|
I'm a little late to the party, but I think that while docs.rs has major flaws that prevent it from being linked directly from crates.io for every crate that don't have a documentation link specified, it is still important to link to docs.rs in one way or another. As of right now I don't think there is a single mention of docs.rs anywhere on the crates.io website, and newcomers that don't know about docs.rs will just give up and try another crate (if there is any equivalent), or try to look at the repository and maybe find a documentation link, but sometimes they might not. What we could do instead is create a link "Documentation link missing" right where the "Documentation" link usually is, and create a new page on crates.io named "Help! There is no documentation for my crate !", and explain on this page that there is a nice website called docs.rs that hosts documentation for every crate, but that this website is in no way officially supported and some crates might be missing or even incorrect have documentation some rare cases. I'm just saying this cause experienced users know about docs.rs, but new users might not know at all about this website. If we could give newcomers a hand to find proper documentation for every crate, I think that would be a huge plus, even if it's as small as saying "we don't officially support this but there is this website hosting docs if you want" |
Docs.rs will provide build as json from following URL: `https://docs.rs/crate/<CRATE_NAME>/<CRATE_VERSION>/builds.json`. A get request to this URL will return a list of build attempts. First object in this list will always contain latest build attempt. This object will contain following fields: Example output of `https://docs.rs/crate/rand/0.3.15/builds.json`: ```json [ { "build_status":true, "build_time":"2016-12-29T10:10:49Z", "build_time_relative":"Dec 29, 2016", "cratesfyi_version":"cratesfyi 0.2.3 (eea831c 2016-12-29)", "id":1, "output":null, "rustc_version":"rustc 1.15.0-nightly (71c06a56a 2016-12-18)" } ] ``` `build_status` is `true` if docs.rs successfully built documentation of a crate and `false` if docs.rs failed to build or a crate doesn't have any documentation. This list will contain zero elements if requested crate doesn't exists in docs.rs. Fixes: #87 Ref: rust-lang/crates.io#459 Ref: rust-lang/crates.io#506
|
See #506-- docs.rs now provides a way that crates.io can query for build status, so I'm closing this PR in anticipation that someone will implement a use of that information that only shows a docs.rs link on crates.io if the latest build has succeeded. |
fixes #419
Adding a docs.rs badge and link to the sidebar.
The initial issue said to replace the documentation link but I think that badge will look a bit funny down in a text list so I put it in the sidebar. It also sounds like enough people would be in favor of docs.rs by default and we also already have the crates.io badge up there.