Pull the cargo docs out of tree and convert them to mdBook

[carols10cents]

Part of rust-lang/rust#39588. I didn't see an issue for this yet @steveklabnik so I made one :)

[carols10cents]

@istankovic is working on a draft of this over here! https://github.com/istankovic/cargo-book

[behnam]

Here's an old PR for this: #4220

The content of pages have been updated since this PR and the fork. Not sure how they're going to be handled.

[istankovic]

Heh, just the other day I spent quite some time porting the doc changes made in the meantime to my branch. And now there are additional changes, which I don't mind, really, but I'd like to avoid unnecessary work, if possible. Is there another effort to move the cargo docs to mdbook, that I am not aware of?

[behnam]

I don't know about the migrations, but have been updating the docs recently, because of code changes and improving readability.

[istankovic]

@behnam would you be willing to take over the migration effort? 😄
The way I see it, you're currently updating the docs faster than I can keep up and there's also the fact that I don't have much time, which means the migration will not be done soon.

[behnam]

@istankovic Would be glad to help with Cargo's migration. Although, I haven't worked with mdBook yet and not sure what the plans are overall.

Specifically, I have updated cargo docs to get the online docs like http://doc.crates.io/manifest.html updated, which is considered the reference for manifest syntax. What do we expect to happen to these URLs with the migration?

/ping @carols10cents

[istankovic]

Well, the idea here is to make Cargo docs more like other books, see rust-lang/rust#39588. So you can take a look at how the other books look now, it's very straightforward. You can also checkout the doc-migration branch and run mdbook serve in the book directory to see how it looks like.

The good news is the migration is almost done (modulo your latest changes). The only thing that I did not yet figure out is what to do with the script that builds the docs. This is also probably related to your question about the URLs. Maybe @steveklabnik can give some advice here.

One thing to note is that, unlike other books, this will not be in a separate repo, see the related discussion in the PR.

[carols10cents]

Ok, we talked about this in the cargo team meeting today, and this sort of affects the book too. Here's what we discussed:

• We'd like cargo docs to be available somewhere on doc.rust-lang.org rather than doc.crates.io
• We'd like to have this doc.rust-lang.org URL working for stable cargo docs before december, when the book is getting printed
• To get this on stable, we need to get this done in the next 3 weeks
• That's really quickly
• For now, we can set up a doc.rust-lang.org URL that will redirect to doc.crates.io so that we can use the doc.rust-lang.org URL in the book
• That gives us more time to actually convert the cargo docs to mdbook and set up building/deployment through rust-lang/rust (as discussed in #4220) and have it ride the trains
• When we're ready, we can make the redirects go from doc.crates.io to doc.rust-lang.org instead

I am going to ask the doc team what URL they'd like for the cargo docs, and then I'd like help/pointers from @alexcrichton to set up said redirect to doc.crates.io, and then I can help with getting #4220 rebased and merged in as peoples' schedules allow (but that isn't as urgent as the first two).

Anything I'm forgetting?

[carols10cents]

Any objections to doc.rust-lang.org/cargo? cc @rust-lang/docs

[behnam]

Sounds like a good plan, @carols10cents!

One question: @istankovic mentioned that the new structure is almost ready for the book format, and there's already plenty of the content there, some of which needing updates from upstream. So, it is possible right now to host the new repo on <doc.rust-lang.org>, in an unstable form, and make that the source of truth whenever the content is up-to-date and redirects are set for it from <doc.crates.io>. This way, there's no need to set up redirects in the other direction. Have you considered this option? (I'm curious what may be preventing the new repo going online right now.)

[carols10cents]

(I'm curious what may be preventing the new repo going online right now.)

Since the new structure is going to be deployed through rust-lang/rust, it has to ride the trains. That means it'll only be available at doc.rust-lang.org/nightly/cargo at first, then doc.rust-lang.org/beta/cargo the first time beta branches after that PR makes it in, then doc.rust-lang.org/cargo 6 weeks after that. We want to have a URL to print in the book that needs to definitely go somewhere sometime before December (I don't know when the REALLY hard deadline for that is). I don't want to rush the PR converting the docs because of the book. So for now, we're just going to set up the redirect from doc.rust-lang.org/cargo -> doc.crates.io, make sure that gets into the very next beta, print the doc.rust-lang.org/cargo URL in the book, and then have plenty of time to make the converted docs the way we want them without rushing.

Does that make sense?

[behnam]

Got it! So it's the release schedule for the new repo. Totally makes sense. :)

[istankovic]

Sounds reasonable to me. Still, I'd like to point out once more that the docs are mostly converted. The only changes needed are to port doc updates made by @behnam, which should not be a big deal, and to deal with the infrastucture (build script etc.).

@behnam, if you're willing to do it, I'd be more than happy to hand over the doc-migration effort.

[behnam]

Sure, @istankovic. I can help with that. Would you please also give me some pointers, specially which other docs repo is a good example to look at, specially for build process/scripts?

[istankovic]

You can take a look at how I transferred doc changes here: https://github.com/istankovic/cargo-book/commits/master. For each doc commit in cargo I have a commit in cargo-book which is mostly copy-paste. I changed the original structure somewhat so you need to find appropriate places for the changes, but it is pretty straightforward. Also keeping references up to date should not be a big deal.

[behnam]

We have decided to keep the docs in-repo. We can update the title of this issue.

And the first PR is here: #4453

[behnam]

Related issues:

• Move Crates.io package policies to this repo?
• Merge https://crates.io/install into http://doc.crates.io/#installing

[behnam]

Preview is now live here: http://doc.crates.io/book/

mdBook has a major issue with in-page link generation and we need to wait until the fix lands and makes it to a release, before we add it to the bookshelf. (Upstream fix: rust-lang-nursery/mdBook#419)

I'm also addressing some other small issues and looking forward to more feedback.

[behnam]

Okay, let's close this issue in favor of the follow up here: rust-lang/rust#44910

[alexcrichton]

Sounds great!