From 2e596d52f0322c1e61c49a99d552551038d114e8 Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Wed, 24 Aug 2022 22:12:12 +0100 Subject: [PATCH 1/3] Fix rustdoc warnings when documenting private items --- src/cargo/ops/registry.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/cargo/ops/registry.rs b/src/cargo/ops/registry.rs index b343a813f79..e0aae14e0e8 100644 --- a/src/cargo/ops/registry.rs +++ b/src/cargo/ops/registry.rs @@ -48,13 +48,13 @@ pub enum RegistryConfig { impl RegistryConfig { /// Returns `true` if the credential is [`None`]. /// - /// [`None`]: Credential::None + /// [`None`]: Self::None pub fn is_none(&self) -> bool { matches!(self, Self::None) } /// Returns `true` if the credential is [`Token`]. /// - /// [`Token`]: Credential::Token + /// [`Token`]: Self::Token pub fn is_token(&self) -> bool { matches!(self, Self::Token(..)) } From d12a8e75044c56cc84f7476c9d7aa48594af8c76 Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Wed, 24 Aug 2022 22:11:42 +0100 Subject: [PATCH 2/3] Add rustdoc for lib.rs --- src/cargo/lib.rs | 68 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/src/cargo/lib.rs b/src/cargo/lib.rs index 79d8f954ef9..e93eae04ce9 100644 --- a/src/cargo/lib.rs +++ b/src/cargo/lib.rs @@ -6,6 +6,74 @@ // necessarily an improvement, we prefer to not use them at this time. #![allow(clippy::all)] +//! # Cargo as a library +//! +//! Cargo, the Rust package manager, is also provided as a library. +//! +//! There are two places you can find API documentation of cargo-the-library, +//! +//! - and +//! - . +//! +//! Each of them targets on a slightly different audience. +//! +//! ## For external tool developers +//! +//! The documentation on contains public-facing items in cargo-the-library. +//! External tool developers may find it useful when trying to reuse existing building blocks from Cargo. +//! However, using Cargo as a library has drawbacks, especially cargo-the-library is unstable, +//! and there is no clear path to stabilize it soon at the time of writing. +//! See [The Cargo Book: External tools] for more on this topic. +//! +//! Cargo API documentation on docs.rs gets updates along with each Rust release. +//! Its version always has a 0 major version to state it is unstable. +//! The minor version is always +1 of rustc's minor version +//! (that is, `cargo 0.66.0` corresponds to `rustc 1.65`). +//! +//! ## For Cargo contributors +//! +//! The documentation on contains all items in Cargo. +//! Contributors of Cargo may find it useful as a reference of Cargo's implementation details. +//! It's built with `--document-private-items` rustdoc flag, +//! so you might expect to see some noise and strange items here. +//! The Cargo team and contributors strive for jotting down every details +//! from their brains in each issue and PR. +//! However, something might just disappear in the air with no reason. +//! This documentation can be seen as their extended minds, +//! sharing designs and hacks behind both public and private interfaces. +//! +//! If you are just diving into Cargo internals, [Cargo Architecture Overview] +//! is the best material to get a broader context of how Cargo works under the hood. +//! Things also worth a read are important concepts reside in source code, +//! which Cargo developers have been crafting for a while, namely +//! +//! - [`cargo::core::resolver`](crate::core::resolver), +//! - [`cargo::core::compiler::fingerprint`](core/compiler/fingerprint/index.html), +//! - [`cargo::util::config`](crate::util::config), +//! - [`cargo::ops::fix`](ops/fix/index.html), and +//! - [`cargo::sources::registry`](crate::sources::registry). +//! +//! This API documentation is published on each push of rust-lang/cargo master branch. +//! In other words, it always reflects the latest doc comments in source code on master branch. +//! +//! ## Contribute to Cargo documentations +//! +//! The Cargo team always continues improving all external and internal documentations. +//! If you spot anything could be better, don't hesitate to discuss with the team on +//! Zulip [`t-cargo` stream], or [submit an issue] right on GitHub. +//! There is also an issue label [`A-documenting-cargo-itself`], +//! which is generally for documenting user-facing [The Cargo Book], +//! but the Cargo team is welcome any form of enhancement for the [Cargo Contributor Guide] +//! and this API documentation as well. +//! +//! [The Cargo Book: External tools]: https://doc.rust-lang.org/stable/cargo/reference/external-tools.html +//! [Cargo Architecture Overview]: https://doc.crates.io/contrib/architecture +//! [`t-cargo` stream]: https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo +//! [submit an issue]: https://github.com/rust-lang/cargo/issues/new/choose +//! [`A-documenting-cargo-itself`]: https://github.com/rust-lang/cargo/labels/A-documenting-cargo-itself +//! [The Cargo Book]: https://doc.rust-lang.org/cargo/ +//! [Cargo Contributor Guide]: https://doc.crates.io/contrib/ + use crate::core::shell::Verbosity::Verbose; use crate::core::Shell; use anyhow::Error; From 1c82d9c8c3f00075ea4535fcd5fb86fb8dd99ac6 Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Thu, 25 Aug 2022 11:47:33 +0100 Subject: [PATCH 3/3] Make CI build API doc --- .github/workflows/contrib.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/contrib.yml b/.github/workflows/contrib.yml index 1872ae11ce6..83648780dec 100644 --- a/.github/workflows/contrib.yml +++ b/.github/workflows/contrib.yml @@ -21,6 +21,9 @@ jobs: mkdir mdbook curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.9/mdbook-v0.4.9-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook echo `pwd`/mdbook >> $GITHUB_PATH + - name: Build API doc + run: | + cargo doc --document-private-items --no-deps - name: Deploy docs run: | cd src/doc/contrib @@ -33,6 +36,8 @@ jobs: git update-ref -d refs/heads/gh-pages rm -rf contrib mv ../book contrib + # Move rustdoc under contrib/ + mv ../../../../target/doc contrib/apidoc git add contrib git commit -m "Deploy $GITHUB_SHA to gh-pages" git push --force