Fixed rustdoc, cleaned up buildability of individual crates (#375)

* chore: audited per-crate buildability

* chore: added rustdoc

* chore: explicitly set resolver on workspace

* ci: added doc check task, removed protoc from basic tasks

* docs: fixed broken rustdoc comments

* fix: re-added protoc to ci tasks

.github/workflows/docs-check.yaml

@@ -0,0 +1,33 @@
+name: Docs check
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  clippy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+
+      - name: install protobuf
+        uses: arduino/setup-protoc@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustc, cargo, rust-docs
+
+      - uses: extractions/setup-just@v1
+
+      - name: Build rustdocs
+        run: just rustdoc
+
+      - name: Build doc site
+        run: just docsite

.github/workflows/docs.yaml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup Hugo
         uses: peaceiris/actions-hugo@v2
 
-      - name: install protobuf
+      - name: install protoc
         uses: arduino/setup-protoc@v1
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -18,9 +18,10 @@ node_modules
 crates/wick-rpc/src/generated/wick.rs
 crates/**/src/generated/mod.rs
 /crates/integration/*/build
+docs/static/rustdoc/
 
 
 # misc
 archive
 .vscode/*.log
-.DS_Store
+.DS_Store

Cargo.toml

@@ -1,4 +1,5 @@
 [workspace]
+resolver = "2"
 members = [
   "crates/interfaces/*",
   "crates/integration/test-bdd",

Justfile

@@ -131,6 +131,10 @@ check-unused:
 sanity: early-errors
   just unit-tests
 
+# Build the document site
+docsite:
+  cd docs && hugo --minify
+
 # Run the development hugo server
 devdocs:
   cd docs && hugo serve --disableFastRender --cleanDestinationDir --ignoreCache --gc

crates/wick/flow-component/src/context.rs

@@ -103,8 +103,8 @@ where
   T: std::fmt::Debug,
   T: LocalAwareSend,
 {
-  #[cfg(feature = "invocation")]
   /// Create a new context.
+  #[cfg(feature = "invocation")]
   pub fn new(config: T, inherent: &InherentData, callback: Arc<crate::RuntimeCallback>) -> Self {
     Self {
       inherent: InherentContext {
@@ -116,9 +116,9 @@ where
     }
   }
 
-  #[cfg(not(feature = "invocation"))]
   /// Create a new context.
-  pub fn new(config: T, inherent: InherentData) -> Self {
+  #[cfg(not(feature = "invocation"))]
+  pub fn new(config: T, inherent: &InherentData) -> Self {
     Self {
       inherent: InherentContext {
         rng: Random::from_seed(Seed::unsafe_new(inherent.seed)),

crates/wick/flow-component/src/traits.rs

@@ -45,7 +45,7 @@ pub trait RenderConfiguration {
   /// The configuration source for the implementer.
   type ConfigSource: std::fmt::Debug;
 
-  /// The `decode_config` function decodes a [GenericConfig] into the implementer's configuration type.
+  /// The `decode_config` function decodes a [RuntimeConfig] into the implementer's configuration type.
   fn decode_config(data: Option<Self::ConfigSource>) -> Result<Self::Config, ComponentError>;
 }
 

crates/wick/wick-component-wasm/Cargo.toml

@@ -21,7 +21,7 @@ wick-rpc = { workspace = true }
 wick-wascap = { workspace = true }
 wick-config = { workspace = true }
 wick-oci-utils = { workspace = true }
-flow-component = { workspace = true }
+flow-component = { workspace = true, features = ["invocation"] }
 seeded-random = { workspace = true, features = ["rng", "std"] }
 tokio = { workspace = true, features = ["fs"] }
 parking_lot = { workspace = true }

crates/wick/wick-component/src/lib.rs

@@ -114,12 +114,12 @@ pub mod datetime {
 }
 //
 //
-/// Re-export of [serde_json] utilities;
+/// Re-export of serde_json utilities;
 #[cfg(feature = "json")]
 pub use serde_json::{from_slice, from_str, from_value, json, to_value, Map, Value};
 //
 //
-/// Re-export of [tokio_stream] utilities;
+/// Re-export of tokio_stream utilities;
 pub use tokio_stream::{empty, iter as iter_raw, once as once_raw, Stream, StreamExt};
 //
 //

crates/wick/wick-config/Cargo.toml

@@ -14,7 +14,11 @@ wick-packet = { workspace = true, default-features = false, features = [
   "validation",
   "std"
 ] }
-wick-interface-types = { workspace = true, features = ["yaml", "parser"] }
+wick-interface-types = { workspace = true, features = [
+  "yaml",
+  "parser",
+  "value"
+] }
 wick-asset-reference = { workspace = true }
 regex = { workspace = true }
 serde = { workspace = true, features = ["derive"] }

crates/wick/wick-config/src/config/common/test_case.rs

@@ -127,7 +127,7 @@ impl TestPacket {
   }
 }
 
-/// A utility wrapper for an [Option<PacketFlag>] that allows for more ergonomic assertions.
+/// A utility wrapper for an [Option]-wrapped [PacketFlag] that allows for more ergonomic assertions.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct MaybePacketFlag(Option<PacketFlag>);
 

crates/wick/wick-config/src/error.rs

@@ -90,7 +90,7 @@ pub enum ManifestError {
   #[error("Could not render configuration template: {0}")]
   ConfigurationTemplate(String),
 
-  /// Passed [RuntimeConfig] is invalid for the configuration required by this component.
+  /// Passed [wick_packet::RuntimeConfig] is invalid for the configuration required by this component.
   #[error(transparent)]
   ConfigurationInvalid(#[from] wick_packet::Error),
 

crates/wick/wick-interface-types/src/field.rs

@@ -17,6 +17,7 @@ pub struct Field {
   pub ty: Type,
 
   /// Whether the field is required.
+  #[cfg(feature = "value")]
   #[serde(default, skip_serializing_if = "Option::is_none")]
   pub default: Option<serde_json::Value>,
 
@@ -34,6 +35,7 @@ impl Field {
     Self {
       name: name.as_ref().to_owned(),
       description: None,
+      #[cfg(feature = "value")]
       default: None,
       required: true,
       ty,
@@ -59,6 +61,7 @@ impl Field {
 
   /// Get the default value of the field
   #[must_use]
+  #[cfg(feature = "value")]
   pub fn default(&self) -> Option<&serde_json::Value> {
     self.default.as_ref()
   }
@@ -71,6 +74,7 @@ impl Field {
 
   /// Consume the [Field] and return a [FieldValue] with the given value.
   #[must_use]
+  #[cfg(feature = "value")]
   pub fn with_value(self, value: impl Into<serde_json::Value>) -> FieldValue {
     FieldValue::new(self, value.into())
   }
@@ -85,6 +89,7 @@ impl std::fmt::Display for Field {
 }
 
 /// A field and its value.
+#[cfg(feature = "value")]
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct FieldValue {
   /// The field.
@@ -93,6 +98,7 @@ pub struct FieldValue {
   pub value: serde_json::Value,
 }
 
+#[cfg(feature = "value")]
 impl FieldValue {
   /// Create a new field value.
   #[must_use]

crates/wick/wick-interface-types/src/lib.rs

@@ -102,7 +102,9 @@ mod traits;
 
 mod signatures;
 
-pub use field::{Field, FieldValue};
+pub use field::Field;
+#[cfg(feature = "value")]
+pub use field::FieldValue;
 pub use signatures::*;
 pub use traits::*;
 pub use types::*;

crates/wick/wick-interface-types/src/types.rs

@@ -9,7 +9,6 @@ mod struct_def;
 mod union_def;
 
 use serde::{Deserialize, Serialize};
-use serde_json::Value;
 
 pub use self::enum_def::{EnumDefinition, EnumVariant};
 pub use self::struct_def::StructDefinition;
@@ -153,20 +152,20 @@ impl Type {
       Type::String => TypeId::of::<String>(),
       Type::Datetime => TypeId::of::<String>(),
       Type::Bytes => TypeId::of::<Vec<u8>>(),
-      Type::Named(_) => TypeId::of::<Value>(),
+      Type::Named(_) => TypeId::of::<serde_json::Value>(),
       Type::List { .. } => TypeId::of::<Vec<Box<dyn std::any::Any>>>(),
       Type::Optional { .. } => TypeId::of::<Option<Box<dyn std::any::Any>>>(),
       Type::Map { .. } => TypeId::of::<std::collections::HashMap<Box<dyn std::any::Any>, Box<dyn std::any::Any>>>(),
-      Type::Link { .. } => TypeId::of::<Value>(),
-      Type::Object => TypeId::of::<Value>(),
+      Type::Link { .. } => TypeId::of::<serde_json::Value>(),
+      Type::Object => TypeId::of::<serde_json::Value>(),
       Type::AnonymousStruct(_) => unimplemented!(),
     }
   }
 
   #[cfg(feature = "value")]
-  pub fn coerce_str<'a>(&self, value: &'a str) -> Result<Value, &'a str> {
+  pub fn coerce_str<'a>(&self, value: &'a str) -> Result<serde_json::Value, &'a str> {
     let val = match self {
-      Type::String => Value::String(value.to_owned()),
+      Type::String => serde_json::Value::String(value.to_owned()),
       Type::U8
       | Type::U16
       | Type::U32
@@ -176,29 +175,29 @@ impl Type {
       | Type::I32
       | Type::I64
       | Type::F32
-      | Type::F64 => Value::Number(value.parse().map_err(|_| value)?),
-      Type::Bool => Value::Bool(value.parse().map_err(|_| value)?),
+      | Type::F64 => serde_json::Value::Number(value.parse().map_err(|_| value)?),
+      Type::Bool => serde_json::Value::Bool(value.parse().map_err(|_| value)?),
       Type::Object => match serde_json::from_str(value) {
         Ok(v) => v,
         Err(_) => serde_json::from_str(&format!("\"{}\"", value)).map_err(|_| value)?,
       },
       Type::List { ty } => {
-        let val: Value = serde_json::from_str(value).map_err(|_| value)?;
+        let val: serde_json::Value = serde_json::from_str(value).map_err(|_| value)?;
         if val.is_array() {
           val
         } else {
-          Value::Array(vec![ty.coerce_str(value)?])
+          serde_json::Value::Array(vec![ty.coerce_str(value)?])
         }
       }
-      Type::Datetime => Value::String(value.to_owned()),
-      Type::Bytes => Value::String(value.to_owned()),
-      Type::Named(_) => Value::Object(serde_json::from_str(value).map_err(|_| value)?),
+      Type::Datetime => serde_json::Value::String(value.to_owned()),
+      Type::Bytes => serde_json::Value::String(value.to_owned()),
+      Type::Named(_) => serde_json::Value::Object(serde_json::from_str(value).map_err(|_| value)?),
       Type::Optional { ty } => {
-        return Ok(ty.coerce_str(value).unwrap_or(Value::Null));
+        return Ok(ty.coerce_str(value).unwrap_or(serde_json::Value::Null));
       }
       Type::Map { .. } => serde_json::from_str(value).map_err(|_| value)?,
       Type::Link { .. } => unimplemented!(),
-      Type::AnonymousStruct(_) => Value::Object(serde_json::from_str(value).map_err(|_| value)?),
+      Type::AnonymousStruct(_) => serde_json::Value::Object(serde_json::from_str(value).map_err(|_| value)?),
     };
     Ok(val)
   }
@@ -346,7 +345,7 @@ mod test {
   #[case(TS::U32, "48", json!(48))]
   #[case(TS::List{ty:b(TS::U32)}, "48", json!([48]))]
   #[case(TS::List{ty:b(TS::String)}, "48", json!(["48"]))]
-  fn test_coerce(#[case] ty: Type, #[case] string: &str, #[case] json: Value) -> Result<()> {
+  fn test_coerce(#[case] ty: Type, #[case] string: &str, #[case] json: serde_json::Value) -> Result<()> {
     let val = ty.coerce_str(string).unwrap();
 
     assert_eq!(val, json);

crates/wick/wick-interface-types/src/types/union_def.rs

@@ -20,7 +20,7 @@ pub struct UnionDefinition {
 }
 
 impl UnionDefinition {
-  /// Constructor for [EnumDefinition]
+  /// Constructor for [UnionDefinition]
   pub fn new<T: AsRef<str>>(name: T, types: Vec<Type>) -> Self {
     Self {
       name: name.as_ref().to_owned(),

crates/wick/wick-invocation-server/Cargo.toml

@@ -9,7 +9,7 @@ description = "Generic implementation of a wick RPC server."
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 [dependencies]
 wick-rpc = { workspace = true }
-flow-component = { workspace = true }
+flow-component = { workspace = true, features = ["invocation"] }
 tonic = { workspace = true, features = ["tls"] }
 tokio = { workspace = true, features = ["macros", "net", "rt-multi-thread"] }
 tokio-stream = { workspace = true, features = ["net"] }

crates/wick/wick-packet/src/error.rs

@@ -43,7 +43,7 @@ pub enum Error {
   #[error("Could not retrieve configuration item '{0}'")]
   ContextKey(String),
 
-  /// Returned when trying to decode a non-JSON object into [crate::GenericConfig].
+  /// Returned when trying to decode a non-JSON object into [crate::RuntimeConfig].
   #[error("Can only convert JSON Objects to a operation and component configuration, got '{0}'")]
   BadJson(serde_json::Value),
 

crates/wick/wick-stdlib/Cargo.toml

@@ -11,7 +11,7 @@ description = "The default standard library for the Wick project."
 
 [dependencies]
 wick-packet = { workspace = true }
-flow-component = { workspace = true }
+flow-component = { workspace = true, features = ["invocation"] }
 wick-rpc = { workspace = true }
 wick-interface-types = { workspace = true, features = ["parser"] }
 seeded-random = { workspace = true, features = ["uuid"] }

crates/wick/wick-wascap/src/claims.rs

@@ -23,7 +23,7 @@ pub enum ClaimsOptions {
 }
 
 impl ClaimsOptions {
-  /// Create a new [v0::ClaimsOptions] struct.
+  /// Create a new v0 claims.
   #[must_use]
   pub fn v0(
     revision: Option<u32>,
@@ -39,7 +39,7 @@ impl ClaimsOptions {
     })
   }
 
-  /// Create a new [v1::ClaimsOptions] struct.
+  /// Create a new v1 claims.
   #[must_use]
   pub fn v1(version: Option<String>, expires_in_days: Option<u64>, not_before_days: Option<u64>) -> Self {
     Self::V1(v1::ClaimsOptions {