From 06bcbc7e43643d74650c63624998171f3033900e Mon Sep 17 00:00:00 2001 From: Croxx Date: Tue, 3 Dec 2024 16:32:24 +0800 Subject: [PATCH] doc: enable necessary features when building docs (#812) * doc: enable all features when building docs Signed-off-by: MrCroxx * doc: fix rustdoc for docs.rs with features, add CI Signed-off-by: MrCroxx * chore: make ffmt happy Signed-off-by: MrCroxx * fix: pass rustdoc test for docs.rs Signed-off-by: MrCroxx * fix: fix rustdoc test ci Signed-off-by: MrCroxx * fix: do not build docs for deps Signed-off-by: MrCroxx --------- Signed-off-by: MrCroxx --- .github/workflows/ci.yml | 46 +++++++++++++++++++++++++++++++ Makefile | 1 + foyer-cli/Cargo.toml | 4 --- foyer-memory/src/eviction/lru.rs | 2 +- foyer-memory/src/eviction/mod.rs | 4 --- foyer-memory/src/raw.rs | 2 +- foyer-memory/src/record.rs | 2 +- foyer-storage/src/device/bytes.rs | 2 +- foyer/Cargo.toml | 13 +++++++++ foyer/src/hybrid/builder.rs | 2 +- foyer/src/lib.rs | 1 + foyer/src/prelude.rs | 6 ++++ 12 files changed, 72 insertions(+), 13 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1f3466a5..0bf69f12 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -216,6 +216,52 @@ jobs: CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} with: verbose: true + rustdoc-test: + name: rust doc test + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + runs-on: ${{ matrix.os }} + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Install rust toolchain + uses: dtolnay/rust-toolchain@master + with: + toolchain: nightly + - name: Cache Cargo home + uses: actions/cache@v4 + id: cache + with: + path: | + ~/.cargo/bin/ + ~/.cargo/registry/index/ + ~/.cargo/registry/cache/ + ~/.cargo/git/db/ + key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.toml') }}-${{ env.CACHE_KEY_SUFFIX }}-rustdoc-test + - name: Install NASM for aws-lc-rs on Windows + if: runner.os == 'Windows' + uses: ilammy/setup-nasm@v1 + - name: Install ninja-build tool for aws-lc-fips-sys on Windows + if: runner.os == 'Windows' + uses: seanmiddleditch/gha-setup-ninja@v5 + - name: Run rustdoc test + run: | + cargo test --features "nightly,prometheus,prometheus-client,prometheus-client_0_22,opentelemetry,opentelemetry_0_26,opentelemetry_0_27" --doc + - name: Test docs build with docs.rs + env: + RUSTDOCFLAGS: --cfg docsrs -D warnings + run: | + cargo doc --features "nightly,prometheus,prometheus-client,prometheus-client_0_22,opentelemetry,opentelemetry_0_26,opentelemetry_0_27" --no-deps + - name: Upload docs.rs docs as artifacts + uses: actions/upload-artifact@v4 + with: + name: foyer-docs-${{ github.sha }}-${{ runner.os }} + path: target/doc + if-no-files-found: error + retention-days: 7 + deadlock: name: run with single worker thread and deadlock detection runs-on: ubuntu-latest diff --git a/Makefile b/Makefile index c2a2777b..da0606f4 100644 --- a/Makefile +++ b/Makefile @@ -27,6 +27,7 @@ check-all: test: RUST_BACKTRACE=1 cargo nextest run --all --features "strict_assertions,sanity,prometheus,prometheus-client_0_22,opentelemetry_0_26,opentelemetry_0_27" RUST_BACKTRACE=1 cargo test --doc + RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo +nightly doc --features "nightly,prometheus,prometheus-client,prometheus-client_0_22,opentelemetry,opentelemetry_0_26,opentelemetry_0_27" --no-deps test-ignored: RUST_BACKTRACE=1 cargo nextest run --run-ignored ignored-only --no-capture --workspace --features "strict_assertions,sanity" diff --git a/foyer-cli/Cargo.toml b/foyer-cli/Cargo.toml index c07556b9..7d36f271 100644 --- a/foyer-cli/Cargo.toml +++ b/foyer-cli/Cargo.toml @@ -21,9 +21,5 @@ thiserror = { workspace = true } [dev-dependencies] -[[bin]] -name = "foyer" -path = "src/main.rs" - [lints] workspace = true diff --git a/foyer-memory/src/eviction/lru.rs b/foyer-memory/src/eviction/lru.rs index 63038e5e..c49fa206 100644 --- a/foyer-memory/src/eviction/lru.rs +++ b/foyer-memory/src/eviction/lru.rs @@ -32,7 +32,7 @@ use crate::{ pub struct LruConfig { /// The ratio of the high priority pool occupied. /// - /// [`Lru`] guarantees that the high priority weight are always as larger as + /// `Lru` guarantees that the high priority weight are always as larger as /// but no larger that the capacity * high priority pool ratio. /// /// # Panic diff --git a/foyer-memory/src/eviction/mod.rs b/foyer-memory/src/eviction/mod.rs index f3401fb5..66ac4346 100644 --- a/foyer-memory/src/eviction/mod.rs +++ b/foyer-memory/src/eviction/mod.rs @@ -81,10 +81,6 @@ where /// /// [`Eviction`] is needs to be implemented to support a new cache eviction algorithm. /// -/// For performance considerations, most APIs pass parameters via [`NonNull`] pointers to implement intrusive data -/// structures. It is not required to implement the cache eviction algorithm using the [`NonNull`] pointers. They can -/// also be used as a token for the target entry. -/// /// # Safety /// /// The pointer can be dereferenced as a mutable reference ***iff*** the `self` reference is also mutable. diff --git a/foyer-memory/src/raw.rs b/foyer-memory/src/raw.rs index ed2a0ff1..76a9b64b 100644 --- a/foyer-memory/src/raw.rs +++ b/foyer-memory/src/raw.rs @@ -804,7 +804,7 @@ where } } -/// The state of [`Fetch`]. +/// The state of `fetch`. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum FetchState { /// Cache hit. diff --git a/foyer-memory/src/record.rs b/foyer-memory/src/record.rs index cecfc831..ef30c45c 100644 --- a/foyer-memory/src/record.rs +++ b/foyer-memory/src/record.rs @@ -38,7 +38,7 @@ pub enum CacheHint { Normal, /// Suggest the priority of the entry is low. /// - /// Used by [`crate::eviction::lru::Lru`]. + /// Used by LRU. Low, } diff --git a/foyer-storage/src/device/bytes.rs b/foyer-storage/src/device/bytes.rs index d7dece75..6bc6c43b 100644 --- a/foyer-storage/src/device/bytes.rs +++ b/foyer-storage/src/device/bytes.rs @@ -436,7 +436,7 @@ impl IoBytes { /// /// Otherwise, [`None`] is returned. /// - /// It is strongly recommended to use `into_io_buffer` instead if you don't want to keep the original [`IoByes`] + /// It is strongly recommended to use `into_io_buffer` instead if you don't want to keep the original [`IoBytes`] /// in the [`Err`] path. See `Arc::try_unwrap` and `Arc::into_inner` docs. /// /// Note: The [`IoBytes`] can be a slice of the underlying [`IoBuffer`]. diff --git a/foyer/Cargo.toml b/foyer/Cargo.toml index 2b7c4db9..9a90060f 100644 --- a/foyer/Cargo.toml +++ b/foyer/Cargo.toml @@ -12,6 +12,19 @@ license = { workspace = true } readme = { workspace = true } # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +[package.metadata.docs.rs] +features = [ + "nightly", + # build docs for exporters + "prometheus", + "prometheus-client", + "prometheus-client_0_22", + "opentelemetry", + "opentelemetry_0_26", + "opentelemetry_0_27", +] +rustdoc-args = ["--cfg", "docsrs"] + [dependencies] ahash = { workspace = true } anyhow = "1" diff --git a/foyer/src/hybrid/builder.rs b/foyer/src/hybrid/builder.rs index 45252d87..0f53e7de 100644 --- a/foyer/src/hybrid/builder.rs +++ b/foyer/src/hybrid/builder.rs @@ -269,7 +269,7 @@ where /// /// The admission picker is used to pick the entries that can be inserted into the disk cache store. /// - /// Default: [`AdmitAllPicker`]. + /// Default: [`crate::AdmitAllPicker`]. pub fn with_admission_picker(self, admission_picker: Arc>) -> Self { let builder = self.builder.with_admission_picker(admission_picker); Self { diff --git a/foyer/src/lib.rs b/foyer/src/lib.rs index ecc1a3d4..11b06c36 100644 --- a/foyer/src/lib.rs +++ b/foyer/src/lib.rs @@ -13,6 +13,7 @@ // limitations under the License. #![cfg_attr(feature = "nightly", feature(allocator_api))] +#![cfg_attr(docsrs, feature(doc_cfg))] //! A hybrid cache library that supports plug-and-play cache algorithms, in-memory cache and disk cache. //! diff --git a/foyer/src/prelude.rs b/foyer/src/prelude.rs index 2873547b..f08520b0 100644 --- a/foyer/src/prelude.rs +++ b/foyer/src/prelude.rs @@ -13,16 +13,22 @@ // limitations under the License. #[cfg(feature = "opentelemetry")] +#[cfg_attr(docsrs, doc(cfg(feature = "opentelemetry")))] pub use crate::common::metrics::registry::opentelemetry; #[cfg(feature = "opentelemetry_0_26")] +#[cfg_attr(docsrs, doc(cfg(feature = "opentelemetry_0_26")))] pub use crate::common::metrics::registry::opentelemetry_0_26; #[cfg(feature = "opentelemetry_0_27")] +#[cfg_attr(docsrs, doc(cfg(feature = "opentelemetry_0_27")))] pub use crate::common::metrics::registry::opentelemetry_0_27; #[cfg(feature = "prometheus")] +#[cfg_attr(docsrs, doc(cfg(feature = "prometheus")))] pub use crate::common::metrics::registry::prometheus; #[cfg(feature = "prometheus-client")] +#[cfg_attr(docsrs, doc(cfg(feature = "prometheus-client")))] pub use crate::common::metrics::registry::prometheus_client; #[cfg(feature = "prometheus-client_0_22")] +#[cfg_attr(docsrs, doc(cfg(feature = "prometheus-client_0_22")))] pub use crate::common::metrics::registry::prometheus_client_0_22; pub use crate::{ common::{