docs.rs integration

[steveklabnik]

See this comment for detailed info on what we're currently thinking of for the implementation

Recently, @onur released the awesome https://docs.rs/ , which autogenerates documentation from crates hosted on crates.io.

A lot of people have been asking how this might integrate with crates.io, so I wanted to open this thread to discuss possibilities.

One possibility I'd thought of: we could take any crate which doesn't have a "documentation" link, and replace it with a link to the page on crates.rs. @onur also thought that maybe a badge would work.

/cc @rust-lang/core

[onur]

That is a great idea, but also some crates have broken documentation links. We can also redirect users to docs.rs in this case.

My badge suggestion is, docs.rs have a badge support, example badge for latest version of cargo: And this will be in red if docs.rs fails to build documentation of latest version of cargo. So people can actually see if docs.rs have documentation of crate they are looking for. And showing the latest version is also useful since there is a bit delay (15-30mins) between crates.io and docs.rs. But I have no idea how badges would look like in crates.io or where to put them.

[alexcrichton]

On the technical side I'd be more than willing to also set up webhooks for docs.rs to receive prompt notifications of new versions. Otherwise though we may want to start out with an opt-in form of "integrate this crate with docs.rs" and then gradually we can fill in to all crates that are otherwise missing a documentation link.

I like the idea of a badge here as well, looks nifty to me!

[steveklabnik]

I'd be more than willing to also set up webhooks for docs.rs to receive prompt notifications of new versions

/cc #381

also /cc @ashleygwilliams, npm has stuff like this, and she was even trying to write something to subscribe to them with futures

[nikomatsakis]

I'm in favor of auto-linking to docs.rs :)

[erickt]

Me as well. This will be really handy. Is it possible to hint to docs.rs to build a docs with certain feature flags enabled? This is useful for libraries optionally exposing serde implementations.

[onur]

@erickt that is the next thing I will be working on, see onur/docs.rs#29

[steveklabnik]

Not currently, but it's been one of the most common feature requests.

On Thu, Sep 1, 2016 at 1:31 PM, Erick Tryzelaar notifications@github.com
wrote:

Me as well. This will be really handy. Is it possible to hint to docs.rs
to build a docs with certain feature flags enabled? This is useful for
libraries optionally exposing serde implementations.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#419 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AABsis6aSPifgprZnSn7h6TKe63D4itSks5qlwvbgaJpZM4Jvwrg
.

[joshtriplett]

I'd like to see this as well, for any crates that don't already have documentation links.

Many that do should migrate to docs.rs as well, for convenient cross-referencing; we may want to start steering people in that direction once crates.io uses it by default.

[carols10cents]

Duplicating the status from #459 and #506:

docs.rs now provides a way that crates.io can query for build status, so this issue is now for implementing a use of that information that only shows a docs.rs link on crates.io if the latest build has succeeded.

There's documentation for the way to query docs.rs in: #506 (comment)

[carols10cents]

Ok, so what needs to be done for this is:

• If a crate does not have a documentation link see this if crate.documentation:
  • Ask docs.rs if it has built the docs for this crate's latest version and if the latest build has succeeded, by making a GET request to https://docs.rs/crate/<CRATE_NAME>/<CRATE_VERSION>/builds.json and checking that the first item in the json list has "build_status": true as documented here
    • If docs.rs does have the docs, create a documentation link for this crate to https://docs.rs/crate/<CRATE_NAME>/<CRATE_VERSION> that looks the same as a documentation link that a crate author would specify

As far as specifically how to implement this, I'm not entirely sure, but I'm thinking something along the lines of changing this if crate.documentation to be something like

{{#if crate.documentation}}
    <li><a href="{{crate.documentation}}">Documentation</a></li>
{{else}}
    <li class="docs-rs-link" data-crate="{{crate.name}}" data-version="{{currentVersion.num}}" />
{{/if}}

and then have javascript that looks for $('.docs-rs-link') and for each does the ajax request using the data attributes, then inserting a link into that li if the json response is what we're looking for.

I'm open to better ideas though, I'm not sure if there's a good way to do this with Ember?

Please let me know if you have any questions about working on this!

[carols10cents]

And also document this behavior over in the docs that live in cargo, around here