Import mdBook-based docs and sync #4453

behnam · 2017-08-31T01:31:27Z

Since we decided to keep the mdBook-based docs in-repo, I have imported the existing converted docs from https://github.com/istankovic/cargo-book under /src/doc/book/ here, and have synced the current docs and the mdBook-based ones manually, file-by-file.

I have created a MIGRATION_MAP file, which shows the relationship between old docs and new ones. The first column is the old file, the second column is the canonical location in mdBook, and the rest of columns are globs of other files in mdBook containing content from the old file.

The first and second column of MIGRATION_MAP shall later be used to create redirect rules from doc.crates.io/ to doc.rust-lang.org/cargo/.

I will also add a README file to remind everyone to keep these files in sync during the migration.

There are also two or three small wording fixes here, which I'll note inline.

This is a retry of #4220.

First step for #4040.

Using `mdbook init` command. Also, update `.gitignore` file manually and add a leading slash. (Upstream fix for mdBook: <https://github.com/azerupi/mdBook/pull/413>)

…-variables.md

…g-dependencies.md

rust-highfive · 2017-08-31T01:31:30Z

r? @matklad

(rust_highfive has picked a reviewer for you, use r? to override)

behnam · 2017-08-31T01:33:02Z

cc @alexcrichton, @carols10cents, @istankovic, @steveklabnik.

behnam · 2017-08-31T01:33:55Z

src/doc/manifest.md

@@ -108,7 +108,7 @@ migration.
 ## The `publish`  field (optional)

 The `publish` field can be used to prevent a package from being published to a
-package repository (like *crates.io*) by mistake.
+package registry (like *crates.io*) by mistake.


Small wording fix.

behnam · 2017-08-31T01:34:17Z

src/doc/manifest.md

@@ -520,7 +519,7 @@ If your project is an executable, name the main source file `src/main.rs`. If it
 is a library, name the main source file `src/lib.rs`.

 Cargo will also treat any files located in `src/bin/*.rs` as executables. If your
-executable consist of more than just one source file, you might also use a directory
+executable consists of more than just one source file, you might also use a directory


Small wording fix.

behnam · 2017-08-31T01:34:35Z

src/doc/guide.md

@@ -398,7 +404,7 @@ documentation for more details.

 To test your project on Travis CI, here is a sample `.travis.yml` file:

-```
+```yaml


Small styling fix.

behnam · 2017-08-31T01:35:43Z

src/doc/index.md

-<pre><code class="language-shell">$ cargo build
-<span style="font-weight: bold"
-class="s1">   Compiling</span> hello_world v0.1.0 (file:///path/to/project/hello_world)</code></pre>
+```shell


This and similar changes (replacing code block with triple-backticks) are to be able to keep the content in sync. We are loosing some styling in the shell snippets, but it's fine, since we will loos them eventually anyway.

behnam · 2017-08-31T01:39:15Z

I should mention that, I have checked all pairs of files manually (using vim -d) and sync'ed them.

alexcrichton · 2017-08-31T14:38:34Z

Awesome thanks so much for this!

So in terms of deployment, are you thinking it looks like:

Land this PR, it won't change doc.crates.io
Update rust-lang/rust to produce documentation for doc.rust-lang.org/cargo
Add a redirect from doc.crates.io to doc.rust-lang.org
Update this repository to stop updating doc.crates.io

or maybe something different?

steveklabnik · 2017-08-31T14:51:24Z

@alexcrichton regarding deployment, @carols10cents actually wanted one more step. It should look like this:

Land this PR, it won't change doc.crates.io
Point doc.rust-lang.org/cargo -> doc.crates.io
Update rust-lang/rust to produce documentation for doc.rust-lang.org/cargo
Add a redirect from doc.crates.io to doc.rust-lang.org
Update this repository to stop updating doc.crates.io

The reason is, that way we can print the URL "doc.rust-lang.org/cargo" in the book, and even if this process isn't quite done yet, it will be live.

carols10cents · 2017-08-31T15:38:21Z

Point doc.rust-lang.org/cargo -> doc.crates.io

@steveklabnik I did that part already, and it made it into beta; https://doc.rust-lang.org/beta/cargo redirects to doc.crates.io.

steveklabnik · 2017-08-31T15:53:30Z

Oh! Then nevermind 👍

behnam · 2017-08-31T17:08:54Z

Yes, @alexcrichton. Basically what you said. I just want to groom the mdBook docs a bit more before linking from rust repo. I kept those non-sync changes for a different PR.

Here's my list:

Land this PR, it won't change doc.crates.io
Update mdBook to add a landing/cover page, and some text to getting-started page.
Update rust-lang/rust to produce documentation for doc.rust-lang.org/cargo (will get mdBook to nightly)
Add a redirect from doc.crates.io to doc.rust-lang.org and delete the old files. (This shall wait until mdBook makes it to stable doc.rust-lang.org.)

alexcrichton · 2017-08-31T20:30:51Z

That all sounds great to me!

One last thing before merging, do you think we should go ahead an integrate CI? It'd be nice to have a builder that does the mdbook build to ensure that doesn't regress. Also, maybe temporarily we could publish the book under doc.crates.io/new and just not link to it anywhere? (just for us to poke around in)

behnam · 2017-08-31T20:33:27Z

By the way, I've put up a preview of the latest version (including this PR and the future grooming PR) here: http://code.behnam.es/rust-cargo/src/doc/book/book/

behnam · 2017-08-31T20:40:02Z

One last thing before merging, do you think we should go ahead an integrate CI? It'd be nice to have a builder that does the mdbook build to ensure that doesn't regress. Also, maybe temporarily we could publish the book under doc.crates.io/new and just not link to it anywhere? (just for us to poke around in)

Yeah, makes sense. But let's do so in a separate PR, as this one is already big and these steps may take a bit longer, while I have some work on top of this PR already.

Also, doc.crates.io/new or doc.crates.io/book?

alexcrichton · 2017-08-31T20:42:54Z

@bors: r+

Ok then, let's land this.

I'm fine with either /new or /book

bors · 2017-08-31T20:42:55Z

📌 Commit bd5ecd4 has been approved by alexcrichton

istankovic · 2017-08-31T21:03:30Z

@behnam Thanks so much for taking the time to do this!

bors · 2017-08-31T21:08:16Z

⌛ Testing commit bd5ecd4 with merge 97452de...

Import mdBook-based docs and sync Since we decided to keep the mdBook-based docs in-repo, I have imported the existing converted docs from <https://github.com/istankovic/cargo-book> under `/src/doc/book/` here, and have synced the current docs and the mdBook-based ones manually, file-by-file. I have created a `MIGRATION_MAP` file, which shows the relationship between old docs and new ones. The first column is the old file, the second column is the canonical location in mdBook, and the rest of columns are globs of other files in mdBook containing content from the old file. The first and second column of `MIGRATION_MAP` shall later be used to create redirect rules from `doc.crates.io/` to `doc.rust-lang.org/cargo/`. I will also add a README file to remind everyone to keep these files in sync during the migration. There are also two or three small wording fixes here, which I'll note inline. This is a retry of <#4220>. First step for <#4040>.

bors · 2017-08-31T21:45:15Z

☀️ Test successful - status-appveyor, status-travis
Approved by: alexcrichton
Pushing 97452de to master...

This wording was originally from 58a1804 (At the end, point to docs that might be interesting next, 2016-05-17, rust-lang#2688), which added it to the end of the guide (where telling readers what they know makes some sense). It was moved to a "Cargo in Depth" section with 01aa9e3 ([src/doc/book] Move a paragraph to cargo-in-depth.md, 2017-08-31, rust-lang#4453), where it makes a bit less sense. When that section became the reference index in 3f2d93e ([doc/book] Create dir for book sections, 2017-08-31, rust-lang#4455) the context assumed by the paragraph was completely missing. This commit removes the paragraph, which doesn't reduce the usefulness of the reference index. And the removal avoids confusing readers who start with the reference docs and may now have the assumed overview.

…lexcrichton doc/reference/index: Remove "Now that you have an overview" paragraph This wording was originally from 58a1804 (#2688), which added it to the end of the guide (where telling readers what they know makes some sense). It was moved to a "Cargo in Depth" section with 01aa9e3 (#4453), where it makes a bit less sense. When that section became the reference index in 3f2d93e (#4455) the context assumed by the paragraph was completely missing. This commit removes the paragraph, which doesn't reduce the usefulness of the reference index. And the removal avoids confusing readers who start with the reference docs and may now have the assumed overview.

behnam added 16 commits August 30, 2017 15:38

[src/doc/book] Import from cargo-book repo

4d590f9

[src/doc/book] Add .gitignore

a442f85

Using `mdbook init` command. Also, update `.gitignore` file manually and add a leading slash. (Upstream fix for mdBook: <https://github.com/azerupi/mdBook/pull/413>)

[src/doc/book] Update 03-03-config.md from config.md

e62845c

[src/doc/book] Update 03-05-build-scripts.md from build-script.md

b8820de

[src/doc/book] Update 03-06-crates-io.md from crates-io.md

0776699

[src/doc/book] Update 03-04-environment-variables.md from environment…

93baf1e

…-variables.md

[src/doc/book] Update 03-09-external-tools.md from external-tools.md

ae7889a

[src/doc/book] Check faq.md

72590a3

[src/doc/book] Update guide.md and 02-*.md from guide.md

582f46c

[src/doc/book] Apply 01-*.md changes into index.md

53d5495

[src/doc/book] Update 03-02-manifest.md from manifest.md

917c363

[src/doc/book] Check 03-07-pkgid-spec.md

51be221

[src/doc/book] Update 03-10-policies.md from policies.md

055147f

[src/doc/book] Check 03-08-source-replacement.md

d431fa2

[src/doc/book] Update 03-01-specifying-dependencies.md from specifyin…

d7c5a6b

…g-dependencies.md

[src/doc/book] Update SUMMARY.md

0fdd599

rust-highfive assigned matklad Aug 31, 2017

[src/doc] Add README.md

ec25b8b

behnam commented Aug 31, 2017

View reviewed changes

This was referenced Aug 31, 2017

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

Closed

Doc migration #4220

Closed

behnam force-pushed the book branch from 2fbc5a7 to e6841b9 Compare August 31, 2017 07:52

behnam added 3 commits August 31, 2017 00:53

[src/doc/book] Drop unused images

e6841b9

[src/doc/book] Add all sub-chapters to cargo-in-depth.md

afe693d

[src/doc/book] Move a paragraph to cargo-in-depth.md

01aa9e3

behnam force-pushed the book branch from 51dd34b to bd5ecd4 Compare August 31, 2017 08:35

[src/doc/book] Fix header casings

3fac7b2

[src/doc/book] Use package registry for crates.io

bd5ecd4

bors merged commit bd5ecd4 into rust-lang:master Aug 31, 2017

behnam deleted the book branch August 31, 2017 21:58

behnam mentioned this pull request Oct 25, 2017

Fix documentation for package.readme option. #4644

Merged

tari mentioned this pull request Jan 6, 2018

doc: book migration lost some changes #4906

Closed

wking mentioned this pull request Jan 8, 2018

doc/reference/index: Remove "Now that you have an overview" paragraph #4922

Merged

ehuss added this to the 1.22.0 milestone Feb 6, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Import mdBook-based docs and sync #4453

Import mdBook-based docs and sync #4453

behnam commented Aug 31, 2017 •

edited

Loading

rust-highfive commented Aug 31, 2017

behnam commented Aug 31, 2017

behnam Aug 31, 2017

behnam Aug 31, 2017

behnam Aug 31, 2017

behnam Aug 31, 2017 •

edited

Loading

behnam commented Aug 31, 2017

alexcrichton commented Aug 31, 2017

steveklabnik commented Aug 31, 2017

carols10cents commented Aug 31, 2017

steveklabnik commented Aug 31, 2017

behnam commented Aug 31, 2017

alexcrichton commented Aug 31, 2017

behnam commented Aug 31, 2017

behnam commented Aug 31, 2017

alexcrichton commented Aug 31, 2017

bors commented Aug 31, 2017

istankovic commented Aug 31, 2017

bors commented Aug 31, 2017

bors commented Aug 31, 2017

Import mdBook-based docs and sync #4453

Import mdBook-based docs and sync #4453

Conversation

behnam commented Aug 31, 2017 • edited Loading

rust-highfive commented Aug 31, 2017

behnam commented Aug 31, 2017

behnam Aug 31, 2017

Choose a reason for hiding this comment

behnam Aug 31, 2017

Choose a reason for hiding this comment

behnam Aug 31, 2017

Choose a reason for hiding this comment

behnam Aug 31, 2017 • edited Loading

Choose a reason for hiding this comment

behnam commented Aug 31, 2017

alexcrichton commented Aug 31, 2017

steveklabnik commented Aug 31, 2017

carols10cents commented Aug 31, 2017

steveklabnik commented Aug 31, 2017

behnam commented Aug 31, 2017

alexcrichton commented Aug 31, 2017

behnam commented Aug 31, 2017

behnam commented Aug 31, 2017

alexcrichton commented Aug 31, 2017

bors commented Aug 31, 2017

istankovic commented Aug 31, 2017

bors commented Aug 31, 2017

bors commented Aug 31, 2017

behnam commented Aug 31, 2017 •

edited

Loading

behnam Aug 31, 2017 •

edited

Loading