Update kube-derive/src/lib.rs

Co-authored-by: kazk <kazk.dev@gmail.com>
Signed-off-by: clux <sszynrae@gmail.com>

minor doc improvements

Signed-off-by: clux <sszynrae@gmail.com>

Update architecture.md

Co-authored-by: kazk <kazk.dev@gmail.com>
Signed-off-by: clux <sszynrae@gmail.com>

Update architecture.md

Co-authored-by: kazk <kazk.dev@gmail.com>
Signed-off-by: clux <sszynrae@gmail.com>

Update architecture.md

Co-authored-by: kazk <kazk.dev@gmail.com>
Signed-off-by: clux <sszynrae@gmail.com>

Update architecture.md

Co-authored-by: kazk <kazk.dev@gmail.com>
Signed-off-by: clux <sszynrae@gmail.com>

Update architecture.md

Co-authored-by: kazk <kazk.dev@gmail.com>
Signed-off-by: clux <sszynrae@gmail.com>

Update examples/README.md

Co-authored-by: kazk <kazk.dev@gmail.com>
Signed-off-by: clux <sszynrae@gmail.com>

README.md

@@ -17,7 +17,6 @@ Select a version of `kube` along with the generated [k8s-openapi](https://github
 ```toml
 [dependencies]
 kube = "0.61.0"
-kube-runtime = "0.61.0"
 k8s-openapi = { version = "0.13.1", default-features = false, features = ["v1_22"] }
 ```
 
@@ -32,10 +31,9 @@ All crates herein are versioned and [released](./release.toml) together to guara
 
 ## Usage
 
-See the [examples directory](./examples) for how to use any of these crates.
+See the **[examples directory](./examples)** for how to use any of these crates.
 
 - **[kube API Docs](https://docs.rs/kube/)**
-- **[kube-runtime API Docs](https://docs.rs/kube-runtime/)**
 
 Official examples:
 
@@ -54,19 +52,19 @@ Real world users:
 
 ## Api
 
-The direct `Api` type takes a client, and is constructed with either the `::all` or `::namespaced` functions:
+The [`Api`](https://docs.rs/kube/*/kube/struct.Api.html) is what interacts with kubernetes resources, and is generic over [`Resource`](https://docs.rs/kube/*/kube/trait.Resource.html):
 
 ```rust
 use k8s_openapi::api::core::v1::Pod;
-let pods: Api<Pod> = Api::namespaced(client, "default");
+let pods: Api<Pod> = Api::namespaced(client, "apps");
 
 let p = pods.get("blog").await?;
 println!("Got blog pod with containers: {:?}", p.spec.unwrap().containers);
 
 let patch = json!({"spec": {
     "activeDeadlineSeconds": 5
 }});
-let pp = PatchParams::apply("my_manager");
+let pp = PatchParams::apply("my_controller");
 let patched = pods.patch("blog", &pp, &Patch::Apply(patch)).await?;
 assert_eq!(patched.spec.active_deadline_seconds, Some(5));
 
@@ -105,7 +103,7 @@ There are a ton of kubebuilder-like instructions that you can annotate with here
 
 ## Runtime
 
-The `runtime` module contains sets of higher level abstractions on top of the `Api` and `Resource` types so that you don't have to do all the `watch`/`resourceVersion`/storage book-keeping yourself.
+The `runtime` module exports the `kube_runtime` crate and contains higher level abstractions on top of the `Api` and `Resource` types so that you don't have to do all the `watch`/`resourceVersion`/storage book-keeping yourself.
 
 ### Watchers
 
@@ -168,7 +166,6 @@ Kube has basic support ([with caveats](https://github.com/kube-rs/kube-rs/issues
 ```toml
 [dependencies]
 kube = { version = "0.61.0", default-features = false, features = ["client", "rustls-tls"] }
-kube-runtime = { version = "0.61.0" }
 k8s-openapi = { version = "0.13.1", default-features = false, features = ["v1_22"] }
 ```
 

architecture.md

@@ -137,23 +137,23 @@ The `Discovery` client can be used to do a full recursive sweep of api-groups in
 
 The `discovery` module also contains a way to run smaller queries through the `oneshot` module; e.g. resolving resource name when having group version kind, resolving every resource within one specific group, or even one group at a pinned version.
 
-In equivalent go logic is found in [client-go/discovery](https://github.com/kubernetes/client-go/blob/master/discovery/discovery_client.go)
+The equivalent Go logic is found in [client-go/discovery](https://github.com/kubernetes/client-go/blob/master/discovery/discovery_client.go)
 
 ### kube-derive
-The smallest crate. A simple [derive proc_macro](https://doc.rust-lang.org/reference/procedural-macros.html) to generate kubernetes wrapper structs and trait impls around a data struct.
+The smallest crate. A simple [derive proc_macro](https://doc.rust-lang.org/reference/procedural-macros.html) to generate Kubernetes wrapper structs and trait impls around a data struct.
 
 Uses `darling` to parse `#[kube(attrs...)]` then uses `syn` and `quote` to produce a suitable syntax tree based on the attributes requested.
 
 It ultimately contains a lot of ugly json coercing from attributes into serialization code, but this is code that everyone working with custom resources need.
 
-It has hooks into `schemars` when using `JsonSchema` to ensure the correct type of [crd schema](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema) is attached to the right part of the generated custom resource definition.
+It has hooks into `schemars` when using `JsonSchema` to ensure the correct type of [CRD schema](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema) is attached to the right part of the generated custom resource definition.
 
 ### kube-runtime
-The highest level crate that deals with the highest level abstractions (such as controllers/watchers/reflectors) and specific kubernetes apis that need common care (finalisers, waiting for conditions, event publishing).
+The highest level crate that deals with the highest level abstractions (such as controllers/watchers/reflectors) and specific Kubernetes apis that need common care (finalisers, waiting for conditions, event publishing).
 
 #### watcher
 The `watcher` module contains state machine wrappers around `Api::watch` that will watch and auto-recover on allowable failures.
-The `watcher` fn is the general purpose one that is similar to informers in go land, and will watch a collection of objects. The `watch_object` is a specialised version of this that limits this collection to a single object.
+The `watcher` fn is the general purpose one that is similar to informers in Go land, and will watch a collection of objects. The `watch_object` is a specialised version of this that limits this collection to a single object.
 
 #### reflector
 The `reflector` module contains wrappers around `watcher` that will cache objects in memory.

examples/README.md

@@ -23,7 +23,7 @@ NAMESPACE=dev cargo run --example log_stream -- kafka-manager-7d4f4bd8dc-f6c44
 ```
 
 ## kube admission controller example
-Admission controllers are a bit of a special beast. They don't need actually need `kube_client` (unless you need to verify something with the api-server) or `kube_runtime` (unless you also build a complementing reconciler), because by themselves, they simply get changes sent to them over `https`. You will need a webserver, certificates, and either your controller deployed behind a `Service`, or as we do here: running locally with a private ip that your `k3d` cluster can reach.
+Admission controllers are a bit of a special beast. They don't actually need `kube_client` (unless you need to verify something with the api-server) or `kube_runtime` (unless you also build a complementing reconciler) because, by themselves, they simply get changes sent to them over `https`. You will need a webserver, certificates, and either your controller deployed behind a `Service`, or as we do here: running locally with a private ip that your `k3d` cluster can reach.
 
 ```sh
 export ADMISSION_PRIVATE_IP=192.168.1.163

kube-client/src/config/mod.rs

@@ -1,9 +1,9 @@
-//! Kubernetes configuration objects from `~/.kube/config` or in cluster environment.
+//! Kubernetes configuration objects from `~/.kube/config`, `$KUBECONFIG`, or the [cluster environment](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/#accessing-the-api-from-a-pod).
 //!
-//! Used to populate [`Config`] that is ultimately used to construct a [`Client`][crate::Client].
+//! # Usage
+//! The [`Config`] has several constructors plus logic to infer environment.
 //!
-//! Unless you have issues, prefer using [`Config::infer`] and pass it to a [`Client`][crate::Client].
-
+//! Unless you have issues, prefer using [`Config::infer`], and pass it to a [`Client`][crate::Client].
 mod file_config;
 mod file_loader;
 mod incluster_config;
@@ -17,6 +17,14 @@ pub use file_loader::KubeConfigOptions;
 use std::time::Duration;
 
 /// Configuration object detailing things like cluster URL, default namespace, root certificates, and timeouts.
+///
+/// # Usage
+/// Construct a [`Config`] instance by using one of the many constructors.
+///
+/// Prefer [`Config::infer`] unless you have particular issues, and avoid manually managing
+/// the data in this struct unless you have particular needs. It exists to be consumed by the [`Client`][crate::Client].
+///
+/// If you are looking to parse the kubeconfig found in a user's home directory see [`Kubeconfig`](crate::config::Kubeconfig).
 #[cfg_attr(docsrs, doc(cfg(feature = "config")))]
 #[derive(Debug, Clone)]
 pub struct Config {

kube-derive/src/lib.rs

@@ -88,7 +88,7 @@ mod custom_resource;
 /// Customize the name of the generated root struct (defaults to `kind`).
 ///
 /// ### `#[kube(kube_core = "::kube_core")]`
-/// Customize the crate name the generated code will reach into (defaults to `kube`).
+/// Customize the crate name the generated code will reach into (defaults to `kube::core`).
 /// Should be one of `kube::core`, `kube_client::core` or `kube_core`.
 ///
 /// ### `#[kube(status = "StatusStructName")]`

kube-runtime/src/events/recorder.rs

@@ -81,19 +81,19 @@ impl EventRecorder {
     ///
     /// # Errors
     ///
-    /// Returns an [`Error`](`kube::Error`) if the event is rejected by Kubernetes.
-    pub async fn publish(&self, new_event: NewEvent) -> Result<(), kube_client::Error> {
+    /// Returns an [`Error`](`kube_client::Error`) if the event is rejected by Kubernetes.
+    pub async fn publish(&self, ev: NewEvent) -> Result<(), kube_client::Error> {
         self.event_client
             .create(&PostParams::default(), &Event {
-                action: Some(new_event.action.into()),
-                reason: Some(new_event.reason.into()),
+                action: Some(ev.action.into()),
+                reason: Some(ev.reason.into()),
                 deprecated_count: None,
                 deprecated_first_timestamp: None,
                 deprecated_last_timestamp: None,
                 deprecated_source: None,
                 event_time: MicroTime(Utc::now()),
                 regarding: Some(self.object_reference.clone()),
-                note: new_event.note.map(Into::into),
+                note: ev.note.map(Into::into),
                 metadata: ObjectMeta {
                     namespace: self.object_reference.namespace.clone(),
                     generate_name: Some(format!("{}-", self.event_source.controller)),
@@ -102,11 +102,11 @@ impl EventRecorder {
                 reporting_controller: Some(self.event_source.controller.clone()),
                 reporting_instance: Some(self.event_source.controller_pod.clone().into()),
                 series: None,
-                type_: match new_event.event_type {
+                type_: match ev.event_type {
                     EventType::Normal => Some("Normal".into()),
                     EventType::Warning => Some("Warning".into()),
                 },
-                related: new_event.secondary_object,
+                related: ev.secondary_object,
             })
             .await?;
         Ok(())

kube/src/lib.rs

@@ -1,17 +1,18 @@
-//! Kube is un umbrella-crate for interacting with [Kubernetes](http://kubernetes.io) in rust.
+//! Kube is an umbrella-crate for interacting with [Kubernetes](http://kubernetes.io) in Rust.
 //!
 //! # Overview
 //!
-//! Kube-rs contains a kubernetes client, a controller runtime, a derive macro, and various tooling
-//! required for building applications or controllers that interact with kubernetes.
+//! Kube contains a Kubernetes client, a controller runtime, a custom resource derive, and various tooling
+//! required for building applications or controllers that interact with Kubernetes.
 //!
-//! The main exports are:
+//! The main modules are:
 //!
-//! - [`client`](crate::client) module with the kubernetes `Client`
-//! - [`api`](crate::api) module with the generic kubernetes `Api`
-//! - [`derive`](crate::CustomResource) module with the `CustomResource` derive for building controllers types
-//! - [`runtime`](crate::runtime) module with a `Controller` / `watcher` / `reflector` / `store`
-//! - [`core`](crate::core) module with generics from `apimachinery`
+//! - [`client`](crate::client) with the Kubernetes [`Client`](crate::Client) and its layers
+//! - [`config`](crate::config) for cluster [`Config`](crate::Config)
+//! - [`api`](crate::api) with the generic Kubernetes [`Api`](crate::Api)
+//! - [`derive`](kube_derive) with the [`CustomResource`](crate::CustomResource) derive for building controllers types
+//! - [`runtime`](crate::runtime) with a [`Controller`](crate::runtime::Controller) / [`watcher`](crate::runtime::watcher()) / [`reflector`](crate::runtime::reflector::reflector) / [`Store`](crate::runtime::reflector::Store)
+//! - [`core`](crate::core) with generics from `apimachinery`
 //!
 //! You can use each of these as you need with the help of the [exported features](https://github.com/kube-rs/kube-rs/blob/master/kube/Cargo.toml#L18).
 //!
@@ -23,7 +24,7 @@
 //!
 //! #[tokio::main]
 //! async fn main() -> Result<(), kube::Error> {
-//!     // Infer the runtime environment and try to create a kubernetes Client
+//!     // Infer the runtime environment and try to create a Kubernetes Client
 //!     let client = Client::try_default().await?;
 //!
 //!     // Read pods in the configured namespace into the typed interface from k8s-openapi
@@ -37,9 +38,9 @@
 //!
 //! For details, see:
 //!
-//! - [`Client`](crate::client) for the extensible kubernetes client
-//! - [`Api`](crate::Api) for the generic api methods available on kubernetes resources
-//! - [k8s-openapi](https://docs.rs/k8s-openapi/*/k8s_openapi/) for documentation about the generated kubernetes types
+//! - [`Client`](crate::client) for the extensible Kubernetes client
+//! - [`Api`](crate::Api) for the generic api methods available on Kubernetes resources
+//! - [k8s-openapi](https://docs.rs/k8s-openapi/*/k8s_openapi/) for documentation about the generated Kubernetes types
 //!
 //! # Using the Runtime with the Derive macro
 //!
@@ -95,7 +96,7 @@
 //! For details, see:
 //!
 //! - [`CustomResource`](crate::CustomResource) for documentation how to configure custom resources
-//! - [`runtime::watcher`](crate::runtime::watcher()) for how to long-running watches work and why you want to use this over `Api::watch`
+//! - [`runtime::watcher`](crate::runtime::watcher()) for how to long-running watches work and why you want to use this over [`Api::watch`](crate::Api::watch)
 //! - [`runtime`](crate::runtime) for abstractions that help with more complicated kubernetes application
 //!
 //! # Examples