Merge pull request #366 from flavio/fix-docs

fix docs

.github/workflows/tests.yml

@@ -48,6 +48,19 @@ jobs:
           command: test
           args: --workspace --features full-native-tls,test-registry
 
+  doc:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions-rs/toolchain@16499b5e05bf2e26879000db0c1d13f7e13fa3af # v1.0.7
+        with:
+          profile: minimal
+          toolchain: nightly
+          override: true
+      - run: |
+          make doc
+
   fmt:
     name: Rustfmt
     runs-on: ubuntu-latest

Cargo.toml

@@ -8,6 +8,9 @@ license = "Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/sigstore/sigstore-rs"
 
+[package.metadata.docs.rs]
+all-features = true
+
 [features]
 default = ["full-native-tls", "cached-client", "sigstore-trust-root", "bundle"]
 wasm = ["getrandom/js", "ring/wasm32_unknown_unknown_js", "chrono/wasmbind"]
@@ -44,7 +47,13 @@ sign = ["sigstore_protobuf_specs", "fulcio", "rekor", "cert"]
 verify = ["sigstore_protobuf_specs", "fulcio", "rekor", "cert"]
 bundle = ["sign", "verify"]
 
-sigstore-trust-root = ["sigstore_protobuf_specs", "futures-util", "tough", "regex", "tokio/sync"]
+sigstore-trust-root = [
+  "sigstore_protobuf_specs",
+  "futures-util",
+  "tough",
+  "regex",
+  "tokio/sync",
+]
 
 cosign-native-tls = [
   "oci-distribution/native-tls",
@@ -76,7 +85,10 @@ async-trait = "0.1.52"
 base64 = "0.22.0"
 cached = { version = "0.51.3", optional = true, features = ["async"] }
 cfg-if = "1.0.0"
-chrono = { version = "0.4.27", default-features = false, features = ["now", "serde"] }
+chrono = { version = "0.4.27", default-features = false, features = [
+  "now",
+  "serde",
+] }
 const-oid = { version = "0.9.6", features = ["db"] }
 digest = { version = "0.10.3", default-features = false }
 ecdsa = { version = "0.16.7", features = ["pkcs8", "digest", "der", "signing"] }
@@ -113,7 +125,10 @@ rsa = "0.9.2"
 scrypt = "0.11.0"
 serde = { version = "1.0.136", features = ["derive"] }
 serde_json = "1.0.79"
-serde_with = { version = "3.4.0", features = ["base64", "json"], optional = true }
+serde_with = { version = "3.4.0", features = [
+  "base64",
+  "json",
+], optional = true }
 sha2 = { version = "0.10.6", features = ["oid"] }
 signature = { version = "2.0" }
 sigstore_protobuf_specs = { version = "0.3.2", optional = true }

Makefile

@@ -12,7 +12,7 @@ lint:
 
 .PHONY: doc
 doc:
-	cargo doc
+	RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo +nightly doc --all-features --no-deps
 
 .PHONY: test
 test: fmt lint doc

src/bundle/mod.rs

@@ -18,8 +18,10 @@ pub use sigstore_protobuf_specs::dev::sigstore::bundle::v1::Bundle;
 
 mod models;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "sign")))]
 #[cfg(feature = "sign")]
 pub mod sign;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "verify")))]
 #[cfg(feature = "verify")]
 pub mod verify;

src/bundle/verify/verifier.rs

@@ -206,6 +206,7 @@ impl Verifier {
 impl Verifier {
     /// Constructs an [`Verifier`] against the public-good trust root.
     #[cfg(feature = "sigstore-trust-root")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "sigstore-trust-root")))]
     pub async fn production() -> SigstoreResult<Verifier> {
         let updater = SigstoreTrustRoot::new(None).await?;
 
@@ -279,6 +280,7 @@ pub mod blocking {
     impl Verifier {
         /// Constructs a synchronous [`Verifier`] against the public-good trust root.
         #[cfg(feature = "sigstore-trust-root")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "sigstore-trust-root")))]
         pub fn production() -> SigstoreResult<Verifier> {
             let rt = tokio::runtime::Builder::new_current_thread()
                 .enable_all()

src/cosign/client_builder.rs

@@ -30,15 +30,15 @@ use crate::trust::TrustRoot;
 /// Rekor integration can be enabled by specifying Rekor's public key.
 /// This can be provided via a [`crate::trust::ManualTrustRoot`].
 ///
-/// > Note well: the [`sigstore`](crate::sigstore) module provides helper structs and methods
+/// > Note well: the [`trust::sigstore`](crate::trust::sigstore) module provides helper structs and methods
 /// > to obtain this data from the official TUF repository of the Sigstore project.
 ///
 /// ## Fulcio integration
 ///
 /// Fulcio integration can be enabled by specifying Fulcio's certificate.
-/// This can be provided via a [`crate::sigstore::ManualTrustRoot`].
+/// This can be provided via a [`crate::trust::sigstore::ManualTrustRoot`].
 ///
-/// > Note well: the [`sigstore`](crate::sigstore) module provides helper structs and methods
+/// > Note well: the [`trust::sigstore`](crate::trust::sigstore) module provides helper structs and methods
 /// > to obtain this data from the official TUF repository of the Sigstore project.
 ///
 /// ## Registry caching
@@ -63,6 +63,7 @@ pub struct ClientBuilder<'a> {
 impl<'a> ClientBuilder<'a> {
     /// Enable caching of data returned from remote OCI registries
     #[cfg(feature = "cached-client")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "cached-registry")))]
     pub fn enable_registry_caching(mut self) -> Self {
         self.enable_registry_caching = true;
         self
@@ -71,7 +72,7 @@ impl<'a> ClientBuilder<'a> {
     /// Optional - Configures the roots of trust.
     ///
     /// Enables Fulcio and Rekor integration with the given trust repository.
-    /// See [crate::sigstore::TrustRoot] for more details on trust repositories.
+    /// See [crate::trust::sigstore::TrustRoot] for more details on trust repositories.
     pub fn with_trust_repository<R: TrustRoot + ?Sized>(mut self, repo: &'a R) -> Result<Self> {
         let rekor_keys = repo.rekor_keys()?;
         if !rekor_keys.is_empty() {

src/cosign/mod.rs

@@ -101,12 +101,12 @@ pub trait CosignCapabilities {
     /// must be satisfied:
     ///
     /// * The [`sigstore::cosign::Client`](crate::cosign::client::Client) must
-    ///   have been created with Rekor integration enabled (see [`crate::sigstore::ManualTrustRoot`])
+    ///   have been created with Rekor integration enabled (see [`crate::trust::sigstore::ManualTrustRoot`])
     /// * The [`sigstore::cosign::Client`](crate::cosign::client::Client) must
-    ///   have been created with Fulcio integration enabled (see [`crate::sigstore::ManualTrustRoot])
+    ///   have been created with Fulcio integration enabled (see [`crate::trust::sigstore::ManualTrustRoot])
     /// * The layer must include a bundle produced by Rekor
     ///
-    /// > Note well: the [`sigstore`](crate::sigstore) module provides helper structs and methods
+    /// > Note well: the [`trust::sigstore`](crate::trust::sigstore) module provides helper structs and methods
     /// > to obtain this data from the official TUF repository of the Sigstore project.
     ///
     /// When the embedded certificate cannot be verified, [`SignatureLayer::certificate_signature`]

src/errors.rs

@@ -23,13 +23,15 @@ use crate::cosign::{
 };
 
 #[cfg(feature = "cosign")]
+#[cfg_attr(docsrs, doc(cfg(feature = "cosign")))]
 #[derive(Error, Debug)]
 #[error("Several Signature Layers failed verification")]
 pub struct SigstoreVerifyConstraintsError<'a> {
     pub unsatisfied_constraints: VerificationConstraintRefVec<'a>,
 }
 
 #[cfg(feature = "cosign")]
+#[cfg_attr(docsrs, doc(cfg(feature = "cosign")))]
 #[derive(Error, Debug)]
 #[error("Several Constraints failed to apply on the SignatureLayer")]
 pub struct SigstoreApplicationConstraintsError<'a> {
@@ -135,6 +137,7 @@ pub enum SigstoreError {
 
     // HACK(tnytown): Remove when we rework the Fulcio V2 endpoint.
     #[cfg(feature = "fulcio")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "fulcio")))]
     #[error(transparent)]
     ReqwestError(#[from] reqwest::Error),
 
@@ -163,6 +166,7 @@ pub enum SigstoreError {
     SigstoreNoVerifiedLayer,
 
     #[cfg(feature = "sigstore-trust-root")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "sigstore-trust-root")))]
     #[error(transparent)]
     TufError(#[from] Box<tough::error::Error>),
 

src/lib.rs

@@ -258,29 +258,37 @@
 
 #![forbid(unsafe_code)]
 #![warn(clippy::unwrap_used, clippy::panic)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 pub mod crypto;
 pub mod trust;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "mock-client")))]
 #[cfg(feature = "mock-client")]
 mod mock_client;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "cosign")))]
 #[cfg(feature = "cosign")]
 pub mod cosign;
 
 pub mod errors;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "fulcio")))]
 #[cfg(feature = "fulcio")]
 pub mod fulcio;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "oauth")))]
 #[cfg(feature = "oauth")]
 pub mod oauth;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "registry")))]
 #[cfg(feature = "registry")]
 pub mod registry;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "rekor")))]
 #[cfg(feature = "rekor")]
 pub mod rekor;
 
+#[cfg_attr(docsrs, doc(cfg(any(feature = "sign", feature = "verify"))))]
 #[cfg(any(feature = "sign", feature = "verify"))]
 pub mod bundle;

src/oauth/mod.rs

@@ -15,5 +15,5 @@
 
 pub mod openidflow;
 
-mod token;
+pub mod token;
 pub use token::IdentityToken;

src/registry/config.rs

@@ -147,7 +147,8 @@ pub struct ClientConfig {
     pub protocol: ClientProtocol,
 
     /// Accept invalid hostname. Defaults to false
-    #[cfg(feature = "native-tls")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "full-native-tls")))]
+    #[cfg(feature = "full-native-tls")]
     pub accept_invalid_hostnames: bool,
 
     /// Accept invalid certificates. Defaults to false
@@ -162,7 +163,7 @@ impl Default for ClientConfig {
     fn default() -> Self {
         ClientConfig {
             protocol: ClientProtocol::Https,
-            #[cfg(feature = "native-tls")]
+            #[cfg(feature = "full-native-tls")]
             accept_invalid_hostnames: false,
             accept_invalid_certificates: false,
             extra_root_certificates: Vec::new(),
@@ -175,7 +176,7 @@ impl From<ClientConfig> for oci_distribution::client::ClientConfig {
         oci_distribution::client::ClientConfig {
             protocol: config.protocol.into(),
             accept_invalid_certificates: config.accept_invalid_certificates,
-            #[cfg(feature = "native-tls")]
+            #[cfg(feature = "full-native-tls")]
             accept_invalid_hostnames: config.accept_invalid_hostnames,
             extra_root_certificates: config
                 .extra_root_certificates

src/trust/mod.rs

@@ -15,6 +15,7 @@
 
 use webpki::types::CertificateDer;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "sigstore-trust-root")))]
 #[cfg(feature = "sigstore-trust-root")]
 pub mod sigstore;