-
Notifications
You must be signed in to change notification settings - Fork 2.4k
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(contrib): Move overview to lib #11809
Conversation
This opens more room for additional content
Unfortunately, the intra-doc links seem to follow the same visibility rule as using the API items, meaning that for `lib.rs` to link to a `mod`, it has to have visibility of the `mod`, requiring some mods to be made `pub(crate)` that previously weren't. I've gone ahead and done this for now as the goal of this effort is for us to catch broken docs through refactorings by using intra-doc links. For now, the contrib docs page that was moved just links to the nightly docs. Over time, all of this will just be collapsed into the architecture page which will link out to the nightly docs.
r? @ehuss (rustbot has picked a reviewer for you, use r? to override) |
How do we feel about exposing mods as Any other feedback on this before I commit more time to this effort? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks way better!
Approved as I feel great!
@@ -33,14 +33,14 @@ | |||
|
|||
pub mod artifact; | |||
mod build_config; | |||
mod build_context; | |||
pub(crate) mod build_context; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not really a big deal. Just a bit worried making these modules public. Maintainer now need to gatekeep any misuse during the review.
//! - [`credential`](https://github.com/rust-lang/cargo/tree/master/crates/credential) | ||
//! This subdirectory contains several packages for implementing the | ||
//! experimental | ||
//! [credential-process](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#credential-process) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The layout looks fine here, though I prefer reference-style links. They are more readable at source code level.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I try them every once in a while but always feel like they are more of a pain to initially write (duplicating the referencing, jumping back and forth) and then dealing with later (more places to touch when updating).
Thanks! @bors r+ |
☀️ Test successful - checks-actions |
docs(contrib): Point compilation docs to doc comments This is a follow up to #11809, merging the description of compilation with what is in the source code, leaving a breadcrumb for people who were used to going to the old page (for now). The new entry point for finding this is the doc comment in `lib.rs` Like with #11809, this also meant increasing the visibility of a mod. This mod is mostly re-exported already, so this doesn't seem too bad. I pointed directly to the `job _queue` mod rather than `JobQueue` because the mod had more of an architecture discussion. For `drain_the_queue`, I also pointed at the mod because it talks about it and this avoided making `DrainState` and `drain_the_queue` `pub(crate)`. This still leaves - Files - Part of this indexes the architecture based on files generated and should be in `lib.rs` - Part of this is filesystem best practices and should be moved out of the architecture overview into some kind of Implementation Practices - Package and Resolution - Console Output. This also likely belongs in an Implementation section - Likely stuff in the testing section
This is a follow up to rust-lang#11809 The rest of the file docs will need to be handled in a different way as they are details for people implementing file system interactions.
This is a follow up to rust-lang#11809. On top of what was in the old contrib, I added links out for `.cargo/config.toml`. I'm assuming there are more files that would be worth indexing here but we can add those over time. My focus was on linking to the high-detail documentation. In some cases, this meant increasing visibility to make rustdoc happy. In the registry case, `sources::registry` is a great document to link to so I instead dropped links that rustdoc couldn't handle as they were to details covered in the bigger document or can easily be derived from it. The rest of the file docs will need to be handled in a different way as they are details for people implementing file system interactions.
14 commits in 7d3033d2e59383fd76193daf9423c3d141972a7d..4a3c588b1f0a8e2dc8dd8789dbf3b6a71b02ed49 2023-03-08 17:05:08 +0000 to 2023-03-14 14:05:36 +0000 - ci: make clean-test-output a script for reuse (rust-lang/cargo#11848) - Accurately show status when downgrading dependencies (rust-lang/cargo#11839) - docs(contrib): Move Design Principles earlier in the book (rust-lang/cargo#11842) - docs(contrib): Point compilation docs to doc comments (rust-lang/cargo#11841) - `cargo install --git` multiple packages with binaries found hint (rust-lang/cargo#11835) - Disable flaky auth tests when `gitoxide` runs them (rust-lang/cargo#11830) - Add some documentation on writing cross-compilation tests (rust-lang/cargo#11825) - chore: Use sparse protocol on stable CI (rust-lang/cargo#11829) - Notice for potential unexpected shell expansions in help text of `cargo-add` (rust-lang/cargo#11826) - Add tracking issue to gitoxide unstable docs (rust-lang/cargo#11822) - Bump crates-io to 0.36.0 (rust-lang/cargo#11820) - Bump to 0.71.0; update changelog (rust-lang/cargo#11815) - docs(contrib): Move overview to lib (rust-lang/cargo#11809) - Fix semver check for 1.68 (rust-lang/cargo#11817)
Update cargo 14 commits in 7d3033d2e59383fd76193daf9423c3d141972a7d..4a3c588b1f0a8e2dc8dd8789dbf3b6a71b02ed49 2023-03-08 17:05:08 +0000 to 2023-03-14 14:05:36 +0000 - ci: make clean-test-output a script for reuse (rust-lang/cargo#11848) - Accurately show status when downgrading dependencies (rust-lang/cargo#11839) - docs(contrib): Move Design Principles earlier in the book (rust-lang/cargo#11842) - docs(contrib): Point compilation docs to doc comments (rust-lang/cargo#11841) - `cargo install --git` multiple packages with binaries found hint (rust-lang/cargo#11835) - Disable flaky auth tests when `gitoxide` runs them (rust-lang/cargo#11830) - Add some documentation on writing cross-compilation tests (rust-lang/cargo#11825) - chore: Use sparse protocol on stable CI (rust-lang/cargo#11829) - Notice for potential unexpected shell expansions in help text of `cargo-add` (rust-lang/cargo#11826) - Add tracking issue to gitoxide unstable docs (rust-lang/cargo#11822) - Bump crates-io to 0.36.0 (rust-lang/cargo#11820) - Bump to 0.71.0; update changelog (rust-lang/cargo#11815) - docs(contrib): Move overview to lib (rust-lang/cargo#11809) - Fix semver check for 1.68 (rust-lang/cargo#11817) r? `@ghost`
This is a follow up to rust-lang#11809. On top of what was in the old contrib, I added links out for `.cargo/config.toml`. I'm assuming there are more files that would be worth indexing here but we can add those over time. My focus was on linking to the high-detail documentation. In some cases, this meant increasing visibility to make rustdoc happy. In the registry case, `sources::registry` is a great document to link to so I instead dropped links that rustdoc couldn't handle as they were to details covered in the bigger document or can easily be derived from it. The rest of the file docs will need to be handled in a different way as they are details for people implementing file system interactions.
docs(contrib): Create a file overview in the nightly docs This is a follow up to #11809. On top of what was in the old contrib, I added links out for `.cargo/config.toml`. I'm assuming there are more files that would be worth indexing here but we can add those over time. My focus was on linking to the high-detail documentation. In some cases, this meant increasing visibility to make rustdoc happy. In the registry case, `sources::registry` is a great document to link to so I instead dropped links that rustdoc couldn't handle as they were to details covered in the bigger document or can easily be derived from it. The rest of the file docs will need to be handled in a different way as they are details for people implementing file system interactions.
docs(contrib): Pull impl info out of architecture This is a follow up to #11809. Personally, I found mixing this stuff with architecture less than ideal as it buried the more practical information among details that might not have been as important. With us moving architecture information into doc comments, this provides us an opportunity to rectify this. Not a fan of the name of this chapter but its a start. I've left in the old architecture chapter as there is still content to find a home for (resolver).
docs(contrib): Move higher level resolver docs into doc comments This is a follow up to #11809. I chose `ops::resolve` for most of the old documentation as this because the docs cover the higher level details that include it, like `Cargo.lock` file, while `core::resolver` is more of the algorithm.
What does this PR try to resolve?
Goals
To do this, I am exploring moving contributing documentation to their relevant libraries and linking out to them instead.
How should we test and review this PR?
Look at the PR a commit at a time
Additional information
In moving the content over, I felt a lot of our current intro documentation was a bit verbose, so I tried to shrink it down so that adding more content would not make it overwhelming
Unfortunately, the intra-doc links seem to follow the same visibility
rule as using the API items, meaning that for
lib.rs
to link to amod
, it has to have visibility of themod
, requiring some mods to bemade
pub(crate)
that previously weren't. I've gone ahead and donethis for now as the goal of this effort is for us to catch broken docs
through refactorings by using intra-doc links.
For now, the contrib docs page that was moved just links to the nightly
docs. Over time, all of this will just be collapsed into the
architecture page which will link out to the nightly docs.