Skip to content
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

docs.rs integration #419

Closed
steveklabnik opened this issue Aug 29, 2016 · 11 comments
Closed

docs.rs integration #419

steveklabnik opened this issue Aug 29, 2016 · 11 comments
Labels
A-frontend 🐹 C-enhancement ✨ Category: Adding new behavior or a change to the way an existing feature works E-has-mentor E-help-wanted

Comments

@steveklabnik
Copy link
Member

steveklabnik commented Aug 29, 2016

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
Copy link
Member

onur commented Aug 29, 2016

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: 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
Copy link
Member

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
Copy link
Member Author

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
Copy link

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

@erickt
Copy link

erickt commented Sep 1, 2016

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
Copy link
Member

onur commented Sep 1, 2016

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

@steveklabnik
Copy link
Member Author

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

On Thu, Sep 1, 2016 at 1:31 PM, Erick Tryzelaar [email protected]
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
Copy link
Member

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.

@steveklabnik steveklabnik added C-enhancement ✨ Category: Adding new behavior or a change to the way an existing feature works and removed question ❔ labels Sep 26, 2016
@carols10cents
Copy link
Member

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
Copy link
Member

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
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-frontend 🐹 C-enhancement ✨ Category: Adding new behavior or a change to the way an existing feature works E-has-mentor E-help-wanted
Projects
None yet
Development

Successfully merging a pull request may close this issue.

8 participants