From 053b15c6b48e7b929c8d106ccfbdb2dea875471f Mon Sep 17 00:00:00 2001 From: Apoorv Kothari Date: Mon, 2 Dec 2024 16:43:49 -0800 Subject: [PATCH 1/2] docs: enable feature tagging --- .github/workflows/ci.yml | 13 +++++++------ quic/s2n-quic/Cargo.toml | 8 ++++++++ quic/s2n-quic/src/lib.rs | 10 ++++++++++ quic/s2n-quic/src/provider.rs | 5 +++++ quic/s2n-quic/src/provider/congestion_controller.rs | 1 + quic/s2n-quic/src/provider/tls.rs | 3 +++ 6 files changed, 34 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0b5eba9b9b..11516170ae 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -150,17 +150,18 @@ jobs: with: submodules: true - - name: Install rust toolchain - id: toolchain + # nightly docrs features are used + - name: Install rust nightly toolchain + id: nightly-toolchain run: | - rustup toolchain install stable --profile minimal - rustup override set stable - + rustup toolchain install nightly --profile minimal - uses: camshaft/rust-cache@v1 - name: Run cargo doc - run: cargo doc --all-features --no-deps --workspace --exclude s2n-quic-qns + run: cargo +nightly doc --all-features --no-deps --workspace --exclude s2n-quic-qns + env: + RUSTDOCFLAGS: --cfg s2n_docsrs - uses: aws-actions/configure-aws-credentials@v4.0.2 if: github.event_name == 'push' || github.repository == github.event.pull_request.head.repo.full_name diff --git a/quic/s2n-quic/Cargo.toml b/quic/s2n-quic/Cargo.toml index e0e738d7fa..6eec86737a 100644 --- a/quic/s2n-quic/Cargo.toml +++ b/quic/s2n-quic/Cargo.toml @@ -91,3 +91,11 @@ s2n-quic-transport = { path = "../s2n-quic-transport", features = ["unstable_res tokio = { version = "1", features = ["full"] } tracing = { version = "0.1" } tracing-subscriber = { version = "0.3", features = ["env-filter"] } + +# Compile with the `s2n_docsrs` feature to enable feature tagging in rust docs. See +# documentation for additional configuration options: https://docs.rs/about/metadata +[package.metadata.docs.rs] +rustdoc-args = ["--cfg", "s2n_docsrs"] + +[lints.rust] +unexpected_cfgs = { level = "allow", check-cfg = ['cfg(s2n_docsrs)'] } diff --git a/quic/s2n-quic/src/lib.rs b/quic/s2n-quic/src/lib.rs index a421f50212..e88c2f4dde 100644 --- a/quic/s2n-quic/src/lib.rs +++ b/quic/s2n-quic/src/lib.rs @@ -103,6 +103,16 @@ //! [s2n-tls]: https://github.com/aws/s2n-tls //! [rustls]: https://github.com/rustls/rustls +// Tag docs with the required platform and features. +// https://doc.rust-lang.org/rustdoc/unstable-features.html +#![cfg_attr(s2n_docsrs, feature(doc_cfg))] +#![cfg_attr( + s2n_docsrs, + feature(doc_auto_cfg), + feature(doc_cfg_hide), + doc(cfg_hide(doc)) +)] + #[macro_use] pub mod provider; diff --git a/quic/s2n-quic/src/provider.rs b/quic/s2n-quic/src/provider.rs index cfca4f5f08..7e652bdc47 100644 --- a/quic/s2n-quic/src/provider.rs +++ b/quic/s2n-quic/src/provider.rs @@ -26,6 +26,7 @@ pub(crate) mod sync; cfg_if!( if #[cfg(any(test, feature = "unstable-provider-connection-close-formatter"))] { + #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-connection-close-formatter")))] pub mod connection_close_formatter; } else { #[allow(dead_code)] @@ -35,6 +36,7 @@ cfg_if!( cfg_if!( if #[cfg(any(test, feature = "unstable-provider-packet-interceptor"))] { + #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-packet-interceptor")))] pub mod packet_interceptor; } else { #[allow(dead_code)] @@ -44,6 +46,7 @@ cfg_if!( cfg_if!( if #[cfg(any(test, feature = "unstable-provider-random"))] { + #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-random")))] pub mod random; } else { #[allow(dead_code)] @@ -53,6 +56,7 @@ cfg_if!( cfg_if!( if #[cfg(any(test, feature = "unstable-provider-datagram"))] { + #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-datagram")))] pub mod datagram; } else { #[allow(dead_code)] @@ -62,6 +66,7 @@ cfg_if!( cfg_if!( if #[cfg(any(test, feature = "unstable-provider-dc"))] { + #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-dc")))] pub mod dc; } else { #[allow(dead_code)] diff --git a/quic/s2n-quic/src/provider/congestion_controller.rs b/quic/s2n-quic/src/provider/congestion_controller.rs index 4e529b18a8..0cc8583582 100644 --- a/quic/s2n-quic/src/provider/congestion_controller.rs +++ b/quic/s2n-quic/src/provider/congestion_controller.rs @@ -14,6 +14,7 @@ pub trait Provider { cfg_if! { if #[cfg(feature = "unstable-congestion-controller")] { + #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-congestion-controller")))] // Export the types needed to implement the CongestionController trait pub use s2n_quic_core::{ random::Generator as RandomGenerator, diff --git a/quic/s2n-quic/src/provider/tls.rs b/quic/s2n-quic/src/provider/tls.rs index 2e06543124..4fdb00b30d 100644 --- a/quic/s2n-quic/src/provider/tls.rs +++ b/quic/s2n-quic/src/provider/tls.rs @@ -22,6 +22,7 @@ impl_provider_utils!(); cfg_if! { if #[cfg(feature = "provider-tls-default")] { + #[cfg_attr(s2n_docsrs, doc(cfg(feature = "provider-tls-default")))] pub mod default { //! Provides the recommended implementation of TLS using platform detection pub use super::default_tls::*; @@ -238,6 +239,7 @@ mod default_tls { // TODO stub out default that fails with error when started } +#[cfg_attr(s2n_docsrs, doc(cfg(feature = "provider-tls-rustls")))] #[cfg(feature = "s2n-quic-rustls")] pub mod rustls { //! Provides the [rustls](https://docs.rs/rustls/) implementation of TLS @@ -273,6 +275,7 @@ pub mod rustls { } } +#[cfg_attr(s2n_docsrs, doc(cfg(feature = "provider-tls-s2n")))] #[cfg(feature = "s2n-quic-tls")] pub mod s2n_tls { //! Provides the [s2n-tls](https://github.com/aws/s2n-tls) implementation of TLS From 259e3356453fcfc4a8c615f8213e6dd7646272b7 Mon Sep 17 00:00:00 2001 From: Apoorv Kothari Date: Tue, 3 Dec 2024 14:12:35 -0800 Subject: [PATCH 2/2] rely on the docsrs cfg flag --- .github/workflows/ci.yml | 2 +- quic/s2n-quic/Cargo.toml | 8 -------- quic/s2n-quic/src/lib.rs | 4 ++-- quic/s2n-quic/src/provider.rs | 10 +++++----- quic/s2n-quic/src/provider/congestion_controller.rs | 2 +- quic/s2n-quic/src/provider/tls.rs | 6 +++--- 6 files changed, 12 insertions(+), 20 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 11516170ae..468069eb78 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -161,7 +161,7 @@ jobs: - name: Run cargo doc run: cargo +nightly doc --all-features --no-deps --workspace --exclude s2n-quic-qns env: - RUSTDOCFLAGS: --cfg s2n_docsrs + RUSTDOCFLAGS: --cfg docsrs - uses: aws-actions/configure-aws-credentials@v4.0.2 if: github.event_name == 'push' || github.repository == github.event.pull_request.head.repo.full_name diff --git a/quic/s2n-quic/Cargo.toml b/quic/s2n-quic/Cargo.toml index 6eec86737a..e0e738d7fa 100644 --- a/quic/s2n-quic/Cargo.toml +++ b/quic/s2n-quic/Cargo.toml @@ -91,11 +91,3 @@ s2n-quic-transport = { path = "../s2n-quic-transport", features = ["unstable_res tokio = { version = "1", features = ["full"] } tracing = { version = "0.1" } tracing-subscriber = { version = "0.3", features = ["env-filter"] } - -# Compile with the `s2n_docsrs` feature to enable feature tagging in rust docs. See -# documentation for additional configuration options: https://docs.rs/about/metadata -[package.metadata.docs.rs] -rustdoc-args = ["--cfg", "s2n_docsrs"] - -[lints.rust] -unexpected_cfgs = { level = "allow", check-cfg = ['cfg(s2n_docsrs)'] } diff --git a/quic/s2n-quic/src/lib.rs b/quic/s2n-quic/src/lib.rs index e88c2f4dde..1ef6e1e4d7 100644 --- a/quic/s2n-quic/src/lib.rs +++ b/quic/s2n-quic/src/lib.rs @@ -105,9 +105,9 @@ // Tag docs with the required platform and features. // https://doc.rust-lang.org/rustdoc/unstable-features.html -#![cfg_attr(s2n_docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, feature(doc_cfg))] #![cfg_attr( - s2n_docsrs, + docsrs, feature(doc_auto_cfg), feature(doc_cfg_hide), doc(cfg_hide(doc)) diff --git a/quic/s2n-quic/src/provider.rs b/quic/s2n-quic/src/provider.rs index 7e652bdc47..91a34c4e6e 100644 --- a/quic/s2n-quic/src/provider.rs +++ b/quic/s2n-quic/src/provider.rs @@ -26,7 +26,7 @@ pub(crate) mod sync; cfg_if!( if #[cfg(any(test, feature = "unstable-provider-connection-close-formatter"))] { - #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-connection-close-formatter")))] + #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-connection-close-formatter")))] pub mod connection_close_formatter; } else { #[allow(dead_code)] @@ -36,7 +36,7 @@ cfg_if!( cfg_if!( if #[cfg(any(test, feature = "unstable-provider-packet-interceptor"))] { - #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-packet-interceptor")))] + #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-packet-interceptor")))] pub mod packet_interceptor; } else { #[allow(dead_code)] @@ -46,7 +46,7 @@ cfg_if!( cfg_if!( if #[cfg(any(test, feature = "unstable-provider-random"))] { - #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-random")))] + #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-random")))] pub mod random; } else { #[allow(dead_code)] @@ -56,7 +56,7 @@ cfg_if!( cfg_if!( if #[cfg(any(test, feature = "unstable-provider-datagram"))] { - #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-datagram")))] + #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-datagram")))] pub mod datagram; } else { #[allow(dead_code)] @@ -66,7 +66,7 @@ cfg_if!( cfg_if!( if #[cfg(any(test, feature = "unstable-provider-dc"))] { - #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-provider-dc")))] + #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-dc")))] pub mod dc; } else { #[allow(dead_code)] diff --git a/quic/s2n-quic/src/provider/congestion_controller.rs b/quic/s2n-quic/src/provider/congestion_controller.rs index 0cc8583582..c68704f409 100644 --- a/quic/s2n-quic/src/provider/congestion_controller.rs +++ b/quic/s2n-quic/src/provider/congestion_controller.rs @@ -14,7 +14,7 @@ pub trait Provider { cfg_if! { if #[cfg(feature = "unstable-congestion-controller")] { - #[cfg_attr(s2n_docsrs, doc(cfg(feature = "unstable-congestion-controller")))] + #[cfg_attr(docsrs, doc(cfg(feature = "unstable-congestion-controller")))] // Export the types needed to implement the CongestionController trait pub use s2n_quic_core::{ random::Generator as RandomGenerator, diff --git a/quic/s2n-quic/src/provider/tls.rs b/quic/s2n-quic/src/provider/tls.rs index 4fdb00b30d..978fc26021 100644 --- a/quic/s2n-quic/src/provider/tls.rs +++ b/quic/s2n-quic/src/provider/tls.rs @@ -22,7 +22,7 @@ impl_provider_utils!(); cfg_if! { if #[cfg(feature = "provider-tls-default")] { - #[cfg_attr(s2n_docsrs, doc(cfg(feature = "provider-tls-default")))] + #[cfg_attr(docsrs, doc(cfg(feature = "provider-tls-default")))] pub mod default { //! Provides the recommended implementation of TLS using platform detection pub use super::default_tls::*; @@ -239,7 +239,7 @@ mod default_tls { // TODO stub out default that fails with error when started } -#[cfg_attr(s2n_docsrs, doc(cfg(feature = "provider-tls-rustls")))] +#[cfg_attr(docsrs, doc(cfg(feature = "provider-tls-rustls")))] #[cfg(feature = "s2n-quic-rustls")] pub mod rustls { //! Provides the [rustls](https://docs.rs/rustls/) implementation of TLS @@ -275,7 +275,7 @@ pub mod rustls { } } -#[cfg_attr(s2n_docsrs, doc(cfg(feature = "provider-tls-s2n")))] +#[cfg_attr(docsrs, doc(cfg(feature = "provider-tls-s2n")))] #[cfg(feature = "s2n-quic-tls")] pub mod s2n_tls { //! Provides the [s2n-tls](https://github.com/aws/s2n-tls) implementation of TLS