Docs refresh #2688
Docs refresh #2688
Conversation
Steve and commas, sittin in a tree! Fixes rust-lang/crates.io#334.
I only see `Fresh` if I use `cargo run -v`, but this example uses `cargo run`. Someone following along might not see either of these if they just built in the previous step, though, so clarify that you'll only see that if you have made changes.
This doesn't feel like it fits very well at this point, since our example program doesn't take args and beginners to cargo probably don't have a reason to want to pass flags on to rustc at this point. Also it doesn't even say rustc, just "which flags go where"... where would they go?!?!
Copypasta, or forgotten name change
I'm guessing the path dependency section got added in between. Also linked to the Travis CI rust docs and removed the hyphen since Travis CI seems to spell it without.
Connects to rust-lang#1035. Using crates from crates.io is a common thing that many people will want to know how to do right away and deserves to be part of the main guide.
I think information about specifying dependencies deserves to have its own page since this info is commonly needed and there are a LOT of different ways to specify dependencies. Previously this information was spread across multiple pages, now there's one place to go if you're looking for any of these ways, rather than checking the multiple pages this info was spread across before.
Try to make this flow a bit more and have sections based on what situation you might find yourself in.
|
(rust_highfive has picked a reviewer for you, use r? to override) |
|
❤️ 😍 |
| let’s publish it! Publishing a crate is when a specific version is uploaded to | ||
| crates.io. | ||
| Once you've got a library that you'd like to share with the world, it's time to | ||
| publish it on [crates.io][crates-io]! Publishing a crate is when a specific |
There was a problem hiding this comment.
you don't need to repeat the link text if you're using the same text,
[crates.io]
by itself will work just as well
There was a problem hiding this comment.
you don't need to repeat the link text if you're using the same text,
It's different text, no?
There was a problem hiding this comment.
Nevermind, you addressed it below.
There was a problem hiding this comment.
I actually didn't notice the difference this time, but did below.
There was a problem hiding this comment.
Oh cool! I didn't know you could do this :)
|
Awesome! Thanks so much for this. I like the high-level ideas, and I left a bunch of nits. |
Since they're official rust crates.
|
Thank you so much for the comments @steveklabnik!!!! I think I've addressed them all :) <3 <3 <3 |
| <span style="font-weight: bold" | ||
| class="s1"> Running</span> `target/debug/hello_world` | ||
| Hello, world!</code></pre> | ||
|
|
||
| To pass some arguments to your program, use `cargo run first_arg second_arg`. | ||
| If flags are being passed, use a “--” separator to tell Cargo which flags go where, like `cargo run -- --foo -b bar`. |
There was a problem hiding this comment.
Is this bit of information present elsewhere? It's removed here and never added...
There was a problem hiding this comment.
Yeah, I'm not really sure where would be a good place to move it though, any ideas? It does appear in the help for cargo run:
All of the trailing arguments are passed to the binary to run. If you're passing
arguments to both Cargo and the binary, the ones after `--` go to the binary,
the ones before go to Cargo.
There was a problem hiding this comment.
Perhaps it can be moved to the example with the regex crate? Hardcoded 2014-01-01 looks a bit old school, instead the date can be read from the command line.
On the other hand, I am not sure that this is that valuable info...
Since most projects start with cargo these days.
"External" is a bit confusing. Then if we say where integration tests go, that might make someone wonder where the unit tests go, so I added a note about unit tests.
|
Ok, I think feedback is dying down-- I think this is ready to go in if yinz do :) <3 |
|
👍 |
| native = { path = "native/i686" } | ||
|
|
||
| [target.'cfg(target_pointer_width = "64")'.dependencies] | ||
| native = { path = "native/i686" } |
There was a problem hiding this comment.
This may have actually been a typo in the first version, but the "i686" here is intended to be "x86_64"
There was a problem hiding this comment.
Yup, I moved it from here, I'm happy to fix it though!
|
Awesome, thanks so much @carols10cents! Some extra thoughts:
|
|
Thanks @alexcrichton!!
That sounds good!
TIL that I'm also going to sneak in two commits with small changes to the guide based on feedback from a new rust developer :) |
|
Thanks @carols10cents! |
Docs refresh Hi! Sooooo I've been thinking about the cargo docs lately and today I decided to try some of the things I've been thinking about. There are some smaller changes in here, typos and clarifications and stuff, that I'm totally willing to break out into a separate PR(s) if yinz want. My goals for the larger changes were: - **Make one obvious place to go for info on every which way to specify a dependency.** I've found myself clicking around the different doc pages a lot to find the semver syntax, the different keys that can go with a git location, the `path` override syntax, etc. So I made one top-level "Specifying Dependencies" page and moved relevant info from the guide, the manifest page, and the crates.io page. - **Make The Guide a bit more focused.** There were a few topics in there that didn't really fit in the story arc of trying to get someone up and running with cargo-- it veered off into some more advanced topics that I've moved to places I think they fit better. - **Make the crates.io page only about publishing, not using and publishing.** The info about adding dependencies got folded into either the guide or the new specifying dependencies page, so this should close #1035. I'm also thinking about having someone new to rust/cargo try following the guide, but wanted to get a first pass from experienced people :)
|
☀️ Test successful - cargo-cross-linux, cargo-linux-32, cargo-linux-64, cargo-mac-32, cargo-mac-64, cargo-win-gnu-32, cargo-win-gnu-64, cargo-win-msvc-32, cargo-win-msvc-64 |
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.
Hi! Sooooo I've been thinking about the cargo docs lately and today I decided to try some of the things I've been thinking about.
There are some smaller changes in here, typos and clarifications and stuff, that I'm totally willing to break out into a separate PR(s) if yinz want.
My goals for the larger changes were:
pathoverride syntax, etc. So I made one top-level "Specifying Dependencies" page and moved relevant info from the guide, the manifest page, and the crates.io page.I'm also thinking about having someone new to rust/cargo try following the guide, but wanted to get a first pass from experienced people :)