New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

adding docs.rs badge to crate sidebar #459

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
7 participants
@ducks
Copy link
Contributor

ducks commented Oct 18, 2016

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.

screen shot 2016-10-17 at 9 32 06 pm

@steveklabnik

This comment has been minimized.

Copy link
Member

steveklabnik commented Oct 18, 2016

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.

@ducks

This comment has been minimized.

Copy link
Contributor

ducks commented Oct 18, 2016

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?

@onur

This comment has been minimized.

Copy link
Member

onur commented Oct 18, 2016

Interesting, I'd like to know why @briansmith is against docs.rs

@briansmith

This comment has been minimized.

Copy link

briansmith commented Oct 18, 2016

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 RSAKeyPair documentation (compare https://docs.rs/ring/0.4.3/ring/signature/index.html to https://briansmith.org/rustdoc/ring/signature/index.html). See https://github.com/onur/docs.rs/issues/29. It is disappointing that such a basic issue hasn't been resolved even though it was reported right away. Also, docs.rs isn't following the terms of my crates' licenses, which you can read in the LICENSE file of each repo.

@steveklabnik

This comment has been minimized.

Copy link
Member

steveklabnik commented Oct 18, 2016

Interesting, I'd like to know why @briansmith is against docs.rs

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.

Why does the Rust team publish the libstd documentation at https://doc.rust-lang.org instead of relying on docs.rs?

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.

Also, docs.rs isn't following the terms of my crates' licenses, which you can read in the LICENSE file of each repo.

Let me make sure that there's an issue open about this, this is important.

@steveklabnik steveklabnik referenced this pull request Oct 18, 2016

Open

Licensing issues #72

@onur

This comment has been minimized.

Copy link
Member

onur commented Oct 18, 2016

@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.

@briansmith

This comment has been minimized.

Copy link

briansmith commented Oct 19, 2016

@briansmith, thanks for feedback. I thought you are against docs.rs when Steve referred you as "very anti-docs.rs". My bad sorry.

I'm definitely not against docs.rs.

Actually first thing Rust team asked me to host std docs when I first released docs.rs. Few other people also asked for it.

Probably this is a misunderstanding and I think it doesn't matter.

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.

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.

@alexcrichton

This comment has been minimized.

Copy link
Member

alexcrichton commented Oct 20, 2016

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 version can be included as well in the URL? I also wonder if we may want tighter integration. For example this could be a dead link for a number of crates if documentation failed to build for one reason or another.

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?

@briansmith

This comment has been minimized.

Copy link

briansmith commented Oct 20, 2016

In terms of the implementation I think we may also want to link to the right version of the documentation, so perhaps version can be included as well in the URL?

I think it's better to link to the latest version like the "Documentation" link does in most cases.

@briansmith I'm curious, if this were added to crates.io would you prefer to opt-out of this link for your crates?

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 <img src> will be able to track people's browsing on the crates.io website. This is one reason why companies are so eager to provide badge-based services for GitHub. An obvious privacy improvement would be to inline the SVG into the HTML instead of using <img src>. Otherwise, I recommend talking with others at Mozilla about the agreements they have with vendors w.r.t. tracking beacons like this.

@onur

This comment has been minimized.

Copy link
Member

onur commented Oct 20, 2016

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.

@briansmith

This comment has been minimized.

Copy link

briansmith commented Oct 20, 2016

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.

@alexcrichton

This comment has been minimized.

Copy link
Member

alexcrichton commented Oct 31, 2016

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 :(

@Cobrand

This comment has been minimized.

Copy link

Cobrand commented Jan 14, 2017

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.
For now docs.rs is the only candidate, but in the future there might be another website with similar-but-better features for generating docs, and everyone will be using it. At that point, we could add to the "Help! There is no documentation for my crate!" page a link to the new rust documentation website.

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"

onur added a commit to rust-lang/docs.rs that referenced this pull request Jan 20, 2017

Provide build info as json string
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
@carols10cents

This comment has been minimized.

Copy link
Member

carols10cents commented Jan 20, 2017

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment