Doc migration

[istankovic]

This is (the last) part of rust-lang/rust#39588.

Docs are moved into a submodule (currently under my account, should probably be in nursery).
Content-wise, it's basically the same, with the following differences:

• completed migration to mdbook
• expanded the part on new project creation
• initial attempt to improve content organization

r? @steveklabnik @alexcrichton

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[bors]

☔ The latest upstream changes (presumably #4227) made this pull request unmergeable. Please resolve the merge conflicts.

[alexcrichton]

Thanks for the PR! @steveklabnik just to clarify, this was the intention to have a separate submodule? I was wondering if we may want to have the files included directly because Cargo's CI is much easier (lightweight) than rust-lang/rust and may not deter contributors?

[steveklabnik]

Oh, so I was imagining this would be a part of rust-lang/rust like all the other bookshelf books. I would also be okay with keeping them in-tree if they're gonna stay in the Cargo repo.

If we do keep them in the cargo repo, then I think the submodule makes less sense; I may have misled you @istankovic !

[alexcrichton]

Just to make sure I understand, when you say "like all the other bookshelf books" that means a git repo in rust-lang and a submodule in rust-lang/rust, right?

[steveklabnik]

Just to make sure I understand, when you say "like all the other bookshelf books" that means a git repo in rust-lang and a submodule in rust-lang/rust, right?

Yes.

Thinking about it though, given that we already include Cargo as a sub-repo, I bet we could leave the docs in the cargo repo, and then have the build system look there instead. It'd be slightly weird as it'd be the only thing out of place, but would save us a repo + submodule.

[alexcrichton]

Yeah that's what I figured. If that's ok @istankovic would you be ok moving over to that? (leaving docs in-repo here)

[istankovic]

Sure. I guess it's also better in the sense that Cargo devs may have easier time updating the docs. I'll update the PR.

[bors]

☔ The latest upstream changes (presumably #4272) made this pull request unmergeable. Please resolve the merge conflicts.

[bors]

☔ The latest upstream changes (presumably #4369) made this pull request unmergeable. Please resolve the merge conflicts.

[carols10cents]

Wait, I think we want to leave the old docs around and continue publishing them to github pages until the new docs have ridden the trains to rust stable, right? So this PR should only add new files and not delete the old docs?

[carols10cents]

Also there are some error messages and man pages that reference docs.crates.io:

• cargo/src/cargo/ops/registry.rs

  Line 170 in ffab519

  http://doc.crates.io/manifest.html#package-metadata \

• cargo/src/bin/owner.rs

  Line 43 in 45148e0

  See http://doc.crates.io/crates-io.html#cargo-owner for detailed documentation

• cargo/src/cargo/ops/cargo_install.rs

  Line 355 in 3751e68

  http://doc.crates.io/specifying-dependencies.html \

• cargo/src/cargo/ops/cargo_package.rs

  Line 120 in 03c0a41

  See http://doc.crates.io/manifest.html#package-metadata for more info.",

• cargo/src/cargo/core/registry.rs

  Line 281 in ffab519

  http://doc.crates.io/specifying-dependencies.html#overriding-dependencies

So these URLs need to remain valid indefinitely (so people stuck on old versions of cargo can still follow them and get the docs they need)-- so we should continue serving the docs from those URLs for now, change them to redirects once this PR rides the trains to stable, and this PR should also update the URLs (and the URLs should have stable/beta/nightly in them????? or not, in which case we can't update the URLs in the code until the docs are on stable?)

[istankovic]

@carols10cents:

Wait, I think we want to leave the old docs around and continue publishing them to github pages until the new docs have ridden the trains to rust stable, right? So this PR should only add new files and not delete the old docs?

Hmm, what about doc updates during that time? One would basically have to maintain the docs in two places. That does not sound optimal to me.

[carols10cents]

Hmm, what about doc updates during that time? One would basically have to maintain the docs in two places. That does not sound optimal to me.

Breaking URLs doesn't sound optimal to me :)

[istankovic]

Rust has broken more important things than URLs so far so... 😃

Seriously, there has to be a nicer solution.

[carols10cents]

Seriously, there has to be a nicer solution.

It'll only be for like 12 weeks.

[behnam]

Based on discussion on #4040

So I'm taking over from @istankovic the migration for Cargo's docs to mdBook. Now I'm confused if we're expected to have a separate repo (cargo-book, based on https://github.com/istankovic/cargo-book/) or want to go along the approach in this PR, that creates a mdBook root under cargo repo.

@alexcrichton, @istankovic, @carols10cents?

(If we're going with a separate repo, we should close this PR and keep the discussion on #4040. If not, I'll try to rebase this work in a new PR.)

[steveklabnik]

I personally don't see the need to make a new repo.

[istankovic]

@behnam, thanks a lot for taking over!
The cargo-book repo contains basically the same thing as the doc-migration branch in my cargo fork. The latter is just a squashed form of the former and the book was put under doc/ (I did not think of a better place, feel free to move it). Note that the idea is to have both the mdbook and the current docs coexisting for some time in cargo, per discussion above.

[behnam]

All sounds good! I'll add a note to /src/doc/README about the migration and keeping them in sync during it.

[alexcrichton]

Thanks for taking this on @behnam! And yeah keeping it all in this repo sounds good to me.

Feel free to ask with any questions!

[behnam]

We can close this PR in favor of #4453 which has more updates, and the tracker issue #4040 .

[behnam]

#reminder This can be closed now. :)

[alexcrichton]

Indeed thansk @behnam!