Skip to content

Commit e1605eb

Browse files
borsbors
committed
Auto merge of #11809 - epage:contrib, r=weihanglo
docs(contrib): Move overview to lib ### What does this PR try to resolve? Goals - Move docs closer to their use to make them more likely to be updated - More exhaustively rely on intra-doc links to keep the links valid through refactorings 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 ```console cargo doc --open cargo doc --allow-private-items --open ``` ### 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 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.
2 parents 7e6687f + 0f9bfb9 commit e1605eb

File tree

5 files changed

+87
-153
lines changed

5 files changed

+87
-153
lines changed

‎src/cargo/core/compiler/mod.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -33,14 +33,14 @@
3333
3434
pub mod artifact;
3535
mod build_config;
36-
mod build_context;
36+
pub(crate) mod build_context;
3737
mod build_plan;
3838
mod compilation;
3939
mod compile_kind;
40-
mod context;
40+
pub(crate) mod context;
4141
mod crate_type;
4242
mod custom_build;
43-
mod fingerprint;
43+
pub(crate) mod fingerprint;
4444
pub mod future_incompat;
4545
mod job_queue;
4646
mod layout;

‎src/cargo/lib.rs

+80-41
Original file line numberDiff line numberDiff line change
@@ -9,53 +9,92 @@
99

1010
//! # Cargo as a library
1111
//!
12-
//! Cargo, the Rust package manager, is also provided as a library.
13-
//!
1412
//! There are two places you can find API documentation of cargo-the-library,
1513
//!
16-
//! - <https://docs.rs/cargo> and
17-
//! - <https://doc.rust-lang.org/nightly/nightly-rustc/cargo>.
18-
//!
19-
//! Each of them targets on a slightly different audience.
20-
//!
21-
//! ## For external tool developers
22-
//!
23-
//! The documentation on <https://docs.rs/cargo> contains public-facing items in cargo-the-library.
24-
//! External tool developers may find it useful when trying to reuse existing building blocks from Cargo.
25-
//! However, using Cargo as a library has drawbacks, especially cargo-the-library is unstable,
26-
//! and there is no clear path to stabilize it soon at the time of writing.
27-
//! See [The Cargo Book: External tools] for more on this topic.
28-
//!
29-
//! Cargo API documentation on docs.rs gets updates along with each Rust release.
30-
//! Its version always has a 0 major version to state it is unstable.
31-
//! The minor version is always +1 of rustc's minor version
32-
//! (that is, `cargo 0.66.0` corresponds to `rustc 1.65`).
33-
//!
34-
//! ## For Cargo contributors
14+
//! - <https://docs.rs/cargo>: targeted at external tool developers using cargo-the-library
15+
//! - Released with every rustc release
16+
//! - <https://doc.rust-lang.org/nightly/nightly-rustc/cargo>: targeted at cargo contributors
17+
//! - Updated on each update of the `cargo` submodule in `rust-lang/rust`
3518
//!
36-
//! The documentation on <https://doc.rust-lang.org/nightly/nightly-rustc/cargo> contains all items in Cargo.
37-
//! Contributors of Cargo may find it useful as a reference of Cargo's implementation details.
38-
//! It's built with `--document-private-items` rustdoc flag,
39-
//! so you might expect to see some noise and strange items here.
40-
//! The Cargo team and contributors strive for jotting down every details
41-
//! from their brains in each issue and PR.
42-
//! However, something might just disappear in the air with no reason.
43-
//! This documentation can be seen as their extended minds,
44-
//! sharing designs and hacks behind both public and private interfaces.
19+
//! **WARNING:** Using Cargo as a library has drawbacks, particulary the API is unstable,
20+
//! and there is no clear path to stabilize it soon at the time of writing. See [The Cargo Book:
21+
//! External tools] for more on this topic.
4522
//!
46-
//! If you are just diving into Cargo internals, [Cargo Architecture Overview]
47-
//! is the best material to get a broader context of how Cargo works under the hood.
48-
//! Things also worth a read are important concepts reside in source code,
49-
//! which Cargo developers have been crafting for a while, namely
23+
//! ## Overview
5024
//!
51-
//! - [`cargo::core::resolver`](crate::core::resolver),
52-
//! - [`cargo::core::compiler::fingerprint`](core/compiler/fingerprint/index.html),
53-
//! - [`cargo::util::config`](crate::util::config),
54-
//! - [`cargo::ops::fix`](ops/fix/index.html), and
55-
//! - [`cargo::sources::registry`](crate::sources::registry).
25+
//! - [`ops`]:
26+
//! Every major operation is implemented here. Each command is a thin wrapper around ops.
27+
//! - [`ops::cargo_compile`]:
28+
//! This is the entry point for all the compilation commands. This is a
29+
//! good place to start if you want to follow how compilation starts and
30+
//! flows to completion.
31+
//! - [`core::resolver`]:
32+
//! This is the dependency and feature resolvers.
33+
//! - [`core::compiler`]:
34+
//! This is the code responsible for running `rustc` and `rustdoc`.
35+
//! - [`core::compiler::build_context`]:
36+
//! The [`BuildContext`]['core::compiler::BuildContext] is the result of the "front end" of the
37+
//! build process. This contains the graph of work to perform and any settings necessary for
38+
//! `rustc`. After this is built, the next stage of building is handled in
39+
//! [`Context`][core::compiler::Context].
40+
//! - [`core::compiler::context`]:
41+
//! The `Context` is the mutable state used during the build process. This
42+
//! is the core of the build process, and everything is coordinated through
43+
//! this.
44+
//! - [`core::compiler::fingerprint`]:
45+
//! The `fingerprint` module contains all the code that handles detecting
46+
//! if a crate needs to be recompiled.
47+
//! - [`core::source`]:
48+
//! The [`core::Source`] trait is an abstraction over different sources of packages.
49+
//! Sources are uniquely identified by a [`core::SourceId`]. Sources are implemented in the [`sources`]
50+
//! directory.
51+
//! - [`util`]:
52+
//! This directory contains generally-useful utility modules.
53+
//! - [`util::config`]:
54+
//! This directory contains the config parser. It makes heavy use of
55+
//! [serde](https://serde.rs/) to merge and translate config values. The
56+
//! [`util::Config`] is usually accessed from the
57+
//! [`core::Workspace`]
58+
//! though references to it are scattered around for more convenient access.
59+
//! - [`util::toml`]:
60+
//! This directory contains the code for parsing `Cargo.toml` files.
61+
//! - [`ops::lockfile`]:
62+
//! This is where `Cargo.lock` files are loaded and saved.
5663
//!
57-
//! This API documentation is published on each push of rust-lang/cargo master branch.
58-
//! In other words, it always reflects the latest doc comments in source code on master branch.
64+
//! Related crates:
65+
//! - [`cargo-platform`](https://crates.io/crates/cargo-platform)
66+
//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_platform)):
67+
//! This library handles parsing `cfg` expressions.
68+
//! - [`cargo-util`](https://crates.io/crates/cargo-util)
69+
//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_util)):
70+
//! This contains general utility code that is shared between cargo and the testsuite
71+
//! - [`crates-io`](https://crates.io/crates/crates-io)
72+
//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/crates_io)):
73+
//! This contains code for accessing the crates.io API.
74+
//! - [`home`](https://crates.io/crates/home):
75+
//! This library is shared between cargo and rustup and is used for finding their home directories.
76+
//! This is not directly depended upon with a `path` dependency; cargo uses the version from crates.io.
77+
//! It is intended to be versioned and published independently of Rust's release system.
78+
//! Whenever a change needs to be made, bump the version in Cargo.toml and `cargo publish` it manually, and then update cargo's `Cargo.toml` to depend on the new version.
79+
//! - [`cargo-test-support`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-support)
80+
//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_test_support/index.html)):
81+
//! This contains a variety of code to support writing tests
82+
//! - [`cargo-test-macro`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-macro)
83+
//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_test_macro/index.html)):
84+
//! This is the `#[cargo_test]` proc-macro used by the test suite to define tests.
85+
//! - [`credential`](https://github.com/rust-lang/cargo/tree/master/crates/credential)
86+
//! This subdirectory contains several packages for implementing the
87+
//! experimental
88+
//! [credential-process](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#credential-process)
89+
//! feature.
90+
//! - [`mdman`](https://github.com/rust-lang/cargo/tree/master/crates/mdman)
91+
//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/mdman/index.html)):
92+
//! This is a utility for generating cargo's man pages. See [Building the man
93+
//! pages](https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages)
94+
//! for more information.
95+
//! - [`resolver-tests`](https://github.com/rust-lang/cargo/tree/master/crates/resolver-tests)
96+
//! This is a dedicated package that defines tests for the [dependency
97+
//! resolver][core::resolver].
5998
//!
6099
//! ## Contribute to Cargo documentations
61100
//!

‎src/cargo/ops/mod.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ pub use self::vendor::{vendor, VendorOptions};
3434

3535
pub mod cargo_add;
3636
mod cargo_clean;
37-
mod cargo_compile;
37+
pub(crate) mod cargo_compile;
3838
pub mod cargo_config;
3939
mod cargo_doc;
4040
mod cargo_fetch;
@@ -51,7 +51,7 @@ mod cargo_test;
5151
mod cargo_uninstall;
5252
mod common_for_install_and_uninstall;
5353
mod fix;
54-
mod lockfile;
54+
pub(crate) mod lockfile;
5555
pub(crate) mod registry;
5656
mod resolve;
5757
pub mod tree;

‎src/doc/contrib/src/architecture/codebase.md

+1-106
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,3 @@
11
# Codebase Overview
22

3-
This is a very high-level overview of the Cargo codebase.
4-
5-
* [`src/bin/cargo`](https://github.com/rust-lang/cargo/tree/master/src/bin/cargo)
6-
--- Cargo is split in a library and a binary. This is the binary side that
7-
handles argument parsing, and then calls into the library to perform the
8-
appropriate subcommand. Each Cargo subcommand is a separate module here. See
9-
[SubCommands](subcommands.md).
10-
11-
* [`src/cargo/ops`](https://github.com/rust-lang/cargo/tree/master/src/cargo/ops)
12-
--- Every major operation is implemented here. This is where the binary CLI
13-
usually calls into to perform the appropriate action.
14-
15-
* [`src/cargo/ops/cargo_compile/mod.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile/mod.rs)
16-
--- This is the entry point for all the compilation commands. This is a
17-
good place to start if you want to follow how compilation starts and
18-
flows to completion.
19-
20-
* [`src/cargo/core/resolver`](https://github.com/rust-lang/cargo/tree/master/src/cargo/core/resolver)
21-
--- This is the dependency and feature resolvers.
22-
23-
* [`src/cargo/core/compiler`](https://github.com/rust-lang/cargo/tree/master/src/cargo/core/compiler)
24-
--- This is the code responsible for running `rustc` and `rustdoc`.
25-
26-
* [`src/cargo/core/compiler/build_context/mod.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/build_context/mod.rs)
27-
--- The `BuildContext` is the result of the "front end" of the build
28-
process. This contains the graph of work to perform and any settings
29-
necessary for `rustc`. After this is built, the next stage of building
30-
is handled in `Context`.
31-
32-
* [`src/cargo/core/compiler/context`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/context/mod.rs)
33-
--- The `Context` is the mutable state used during the build process. This
34-
is the core of the build process, and everything is coordinated through
35-
this.
36-
37-
* [`src/cargo/core/compiler/fingerprint.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs)
38-
--- The `fingerprint` module contains all the code that handles detecting
39-
if a crate needs to be recompiled.
40-
41-
* [`src/cargo/core/source`](https://github.com/rust-lang/cargo/tree/master/src/cargo/core/source)
42-
--- The `Source` trait is an abstraction over different sources of packages.
43-
Sources are uniquely identified by a `SourceId`. Sources are implemented in
44-
the
45-
[`src/cargo/sources`](https://github.com/rust-lang/cargo/tree/master/src/cargo/sources)
46-
directory.
47-
48-
* [`src/cargo/util`](https://github.com/rust-lang/cargo/tree/master/src/cargo/util)
49-
--- This directory contains generally-useful utility modules.
50-
51-
* [`src/cargo/util/config`](https://github.com/rust-lang/cargo/tree/master/src/cargo/util/config)
52-
--- This directory contains the config parser. It makes heavy use of
53-
[serde](https://serde.rs/) to merge and translate config values. The
54-
`Config` is usually accessed from the
55-
[`Workspace`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/workspace.rs),
56-
though references to it are scattered around for more convenient access.
57-
58-
* [`src/cargo/util/toml`](https://github.com/rust-lang/cargo/tree/master/src/cargo/util/toml)
59-
--- This directory contains the code for parsing `Cargo.toml` files.
60-
61-
* [`src/cargo/ops/lockfile.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/lockfile.rs)
62-
--- This is where `Cargo.lock` files are loaded and saved.
63-
64-
* [`src/doc`](https://github.com/rust-lang/cargo/tree/master/src/doc)
65-
--- This directory contains Cargo's documentation and man pages.
66-
67-
* [`src/etc`](https://github.com/rust-lang/cargo/tree/master/src/etc)
68-
--- These are files that get distributed in the `etc` directory in the Rust release.
69-
The man pages are auto-generated by a script in the `src/doc` directory.
70-
71-
* [`crates`](https://github.com/rust-lang/cargo/tree/master/crates)
72-
--- A collection of independent crates used by Cargo.
73-
74-
## Extra crates
75-
76-
Some functionality is split off into separate crates, usually in the
77-
[`crates`](https://github.com/rust-lang/cargo/tree/master/crates) directory.
78-
79-
* [`cargo-platform`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-platform)
80-
--- This library handles parsing `cfg` expressions.
81-
* [`cargo-test-macro`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-macro)
82-
--- This is a proc-macro used by the test suite to define tests. More
83-
information can be found at [`cargo_test`
84-
attribute](../tests/writing.md#cargo_test-attribute).
85-
* [`cargo-test-support`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-support)
86-
--- This contains a variety of code to support [writing
87-
tests](../tests/writing.md).
88-
* [`cargo-util`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-util)
89-
--- This contains general utility code that is shared between cargo and the
90-
testsuite.
91-
* [`crates-io`](https://github.com/rust-lang/cargo/tree/master/crates/crates-io)
92-
--- This contains code for accessing the crates.io API.
93-
* [`credential`](https://github.com/rust-lang/cargo/tree/master/crates/credential)
94-
--- This subdirectory contains several packages for implementing the
95-
experimental
96-
[credential-process](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#credential-process)
97-
feature.
98-
* [`home`](https://github.com/rust-lang/cargo/tree/master/crates/home) --- This library is shared between cargo and rustup and is used for finding their home directories.
99-
This is not directly depended upon with a `path` dependency; cargo uses the version from crates.io.
100-
It is intended to be versioned and published independently of Rust's release system.
101-
Whenever a change needs to be made, bump the version in Cargo.toml and `cargo publish` it manually, and then update cargo's `Cargo.toml` to depend on the new version.
102-
* [`mdman`](https://github.com/rust-lang/cargo/tree/master/crates/mdman)
103-
--- This is a utility for generating cargo's man pages. See [Building the man
104-
pages](https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages)
105-
for more information.
106-
* [`resolver-tests`](https://github.com/rust-lang/cargo/tree/master/crates/resolver-tests)
107-
--- This is a dedicated package that defines tests for the [dependency
108-
resolver](../architecture/packages.md#resolver).
3+
See [nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/index.html)

‎src/doc/contrib/src/architecture/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ intended to give you links into the code which is hopefully commented with
55
more in-depth information.
66

77
If you feel something is missing that would help you, feel free to ask on
8-
Zulip.
8+
[Zulip](https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo).

0 commit comments

Comments
 (0)