Simplify doc management

Signed-off-by: Maksym Pavlenko <[email protected]>
containerd · Sep 28, 2023 · 65e5ddf · 65e5ddf
1 parent 1a18196
commit 65e5ddf
Show file tree

Hide file tree

Showing 14 changed files with 83 additions and 125 deletions.
diff --git a/crates/client/Cargo.toml b/crates/client/Cargo.toml
@@ -34,9 +34,13 @@ tonic-build.workspace = true
 
 [features]
 connect = ["tokio", "tower"]
+docs = []
 
 # Technically Tonic doesn't require Tokio and Tower dependencies here.
 # However we need them to implement `connect` helper and it's highly unlikely
 # that Tonic will be used with any other async runtime (see https://github.com/hyperium/tonic/issues/152)
 # So we enable `connect` feature by default (use `--no-default-features` otherwise).
 default = ["connect"]
+
+[package.metadata.docs.rs]
+features = ["docs"]
diff --git a/crates/client/src/lib.rs b/crates/client/src/lib.rs
@@ -14,12 +14,11 @@
    limitations under the License.
 */
 
+#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
 // No way to derive Eq with tonic :(
 // See https://github.com/hyperium/tonic/issues/1056
 #![allow(clippy::derive_partial_eq_without_eq)]
 
-//! A GRPC client to query containerd's API.
-
 pub use tonic;
 
 /// Generated `containerd.types` types.

diff --git a/crates/logging/Cargo.toml b/crates/logging/Cargo.toml
@@ -3,7 +3,7 @@ name = "containerd-shim-logging"
 version = "0.1.1"
 authors = [
   "Maksym Pavlenko <[email protected]>",
-  "The containerd Authors"
+  "The containerd Authors",
 ]
 description = "Logger extension for containerd v2 runtime"
 keywords = ["containerd", "shim", "containers"]
@@ -13,3 +13,9 @@ edition.workspace = true
 license.workspace = true
 repository.workspace = true
 homepage.workspace = true
+
+[features]
+docs = []
+
+[package.metadata.docs.rs]
+features = ["docs"]
diff --git a/crates/logging/src/lib.rs b/crates/logging/src/lib.rs
@@ -14,14 +14,7 @@
    limitations under the License.
 */
 
-//! Helper library to implement custom shim loggers for containerd.
-//!
-//! # Runtime
-//! containerd shims may support pluggable logging via stdio URIs. Binary logging has the ability to
-//! forward a container's STDIO to an external binary for consumption.
-//!
-//! This crates replicates APIs provided by Go [version](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md#logging).
-//!
+#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
 
 use std::{env, fmt, fs, os::unix::io::FromRawFd, process};
 

diff --git a/crates/runc/Cargo.toml b/crates/runc/Cargo.toml
@@ -1,10 +1,7 @@
 [package]
 name = "runc"
 version = "0.2.0"
-authors = [
-  "Yuna Tomida <[email protected]>",
-  "The containerd Authors",
-]
+authors = ["Yuna Tomida <[email protected]>", "The containerd Authors"]
 description = "A crate for consuming the runc binary in your Rust applications"
 keywords = ["containerd", "containers", "runc"]
 categories = ["api-bindings", "asynchronous"]
@@ -16,6 +13,7 @@ homepage.workspace = true
 
 [features]
 async = ["tokio", "async-trait", "futures", "tokio-pipe"]
+docs = []
 
 [dependencies]
 libc.workspace = true
@@ -36,4 +34,7 @@ uuid.workspace = true
 async-trait = { workspace = true, optional = true }
 futures = { workspace = true, optional = true }
 tokio = { workspace = true, features = ["full"], optional = true }
-tokio-pipe = { version="0.2.10", optional = true }
+tokio-pipe = { version = "0.2.10", optional = true }
+
+[package.metadata.docs.rs]
+features = ["docs"]
diff --git a/crates/runc/src/lib.rs b/crates/runc/src/lib.rs
@@ -33,6 +33,8 @@
  * limitations under the License.
  */
 
+#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
+
 //! A crate for consuming the runc binary in your Rust applications, similar to
 //! [go-runc](https://github.com/containerd/go-runc) for Go.
 use std::{

diff --git a/crates/shim-protos/Cargo.toml b/crates/shim-protos/Cargo.toml
@@ -18,6 +18,7 @@ homepage.workspace = true
 default = []
 async = ["ttrpc/async", "async-trait"]
 sandbox = []
+docs = []
 
 [[example]]
 name = "shim-proto-server"
@@ -61,5 +62,10 @@ ttrpc-codegen = "0.4"
 [dev-dependencies]
 ctrlc = { version = "3.0", features = ["termination"] }
 log.workspace = true
-simple_logger = { version = "4.0", default-features = false, features = ["stderr"]}
+simple_logger = { version = "4.0", default-features = false, features = [
+  "stderr",
+] }
 tokio = { workspace = true, features = ["full"] }
+
+[package.metadata.docs.rs]
+features = ["docs"]
diff --git a/crates/shim-protos/README.md b/crates/shim-protos/README.md
@@ -5,13 +5,28 @@
 [![Crates.io](https://img.shields.io/crates/l/containerd-shim-protos)](https://github.com/containerd/rust-extensions/blob/main/LICENSE)
 [![CI](https://github.com/containerd/rust-extensions/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/containerd/rust-extensions/actions/workflows/ci.yml)
 
-TTRPC bindings for containerd's shim events and interfaces.
+`containerd-shim-protos` contains TTRPC bindings and client/server code to interact with containerd's runtime v2 shims.
 
-## Design
+## Runtime
+This crate is mainly expected to be useful to interact with containerd's shim runtime.
+Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd.
+The shim API is minimal and scoped to the execution lifecycle of a container.
+
+To learn how containerd's shim v2 runtime works in details, please refer to the [documentation](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md).
 
+## Design
 The `containerd-shim-protos` crate provides [Protobuf](https://github.com/protocolbuffers/protobuf.git) message
 and [TTRPC](https://github.com/containerd/ttrpc.git) service definitions for the
-[Containerd shim v2](https://github.com/containerd/containerd/blob/main/api/runtime/task/v2/shim.proto) protocol.
+[Containerd shim v2](https://github.com/containerd/containerd/blob/main/runtime/v2/task/shim.proto) protocol.
+
+The message and service definitions are auto-generated from protobuf source files under `vendor/`
+by using [ttrpc-codegen](https://github.com/containerd/ttrpc-rust/tree/master/ttrpc-codegen). So please do not
+edit those auto-generated source files.
+
+If upgrading/modification is needed, please follow the steps:
+ - Synchronize the latest protobuf source files from the upstream projects into directory 'vendor/'.
+ - Re-generate the source files by `cargo build --features=generate_bindings`.
+ - Commit the synchronized protobuf source files and auto-generated source files, keeping them in synchronization.
 
 ## Usage
 Add `containerd-shim-client` as a dependency in your `Cargo.toml`

diff --git a/crates/shim-protos/src/lib.rs b/crates/shim-protos/src/lib.rs
@@ -14,52 +14,7 @@
    limitations under the License.
 */
 
-//! `containerd-shim-protos` contains TTRPC bindings and client/server code to interact with
-//! containerd's runtime v2 shims.
-//!
-//! # Runtime
-//! This crate is mainly expected to be useful to interact with containerd's shim runtime.
-//! Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd.
-//! The shim API is minimal and scoped to the execution lifecycle of a container.
-//!
-//! To learn how containerd's shim v2 runtime works in details, please refer to the [documentation](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md).
-//!
-//! # Design
-//! The `containerd-shim-protos` crate provides [Protobuf](https://github.com/protocolbuffers/protobuf.git) message
-//! and [TTRPC](https://github.com/containerd/ttrpc.git) service definitions for the
-//! [Containerd shim v2](https://github.com/containerd/containerd/blob/main/runtime/v2/task/shim.proto) protocol.
-//!
-//! The message and service definitions are auto-generated from protobuf source files under `vendor/`
-//! by using [ttrpc-codegen](https://github.com/containerd/ttrpc-rust/tree/master/ttrpc-codegen). So please do not
-//! edit those auto-generated source files.
-//!
-//! If upgrading/modification is needed, please follow the steps:
-//! - Synchronize the latest protobuf source files from the upstream projects into directory 'vendor/'.
-//! - Re-generate the source files by `cargo build --features=generate_bindings`.
-//! - Commit the synchronized protobuf source files and auto-generated source files, keeping them in synchronization.
-//!
-//! # Examples
-//!
-//! Here is a quick example how to use the crate:
-//! ```no_run
-//! use containerd_shim_protos as client;
-//!
-//! use client::api;
-//! use client::ttrpc::context::Context;
-//!
-//! // Create TTRPC client
-//! let client = client::Client::connect("unix:///socket.sock").unwrap();
-//!
-//! // Get task client
-//! let task_client = client::TaskClient::new(client);
-//! let context = Context::default();
-//!
-//! // Send request and receive response
-//! let request = api::ConnectRequest::default();
-//! let response = task_client.connect(Context::default(), &request);
-//! ```
-//!
-
+#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
 #![allow(warnings)]
 
 pub use protobuf;

diff --git a/crates/shim/Cargo.toml b/crates/shim/Cargo.toml
@@ -22,6 +22,7 @@ async = [
   "signal-hook-tokio",
   "tokio",
 ]
+docs = []
 
 [[example]]
 name = "skeleton_async"
@@ -36,7 +37,7 @@ containerd-shim-protos = { path = "../shim-protos", version = "0.5.0" }
 go-flag = "0.1.0"
 lazy_static = "1.4.0"
 libc.workspace = true
-log = { workspace = true, features = ["std"]}
+log = { workspace = true, features = ["std"] }
 nix.workspace = true
 oci-spec.workspace = true
 page_size = "0.6.0"
@@ -49,8 +50,10 @@ time.workspace = true
 
 # Async dependencies
 async-trait = { workspace = true, optional = true }
-futures = { workspace = true, optional = true}
-signal-hook-tokio = { version = "0.3.1", optional = true, features = ["futures-v0_3"]}
+futures = { workspace = true, optional = true }
+signal-hook-tokio = { version = "0.3.1", optional = true, features = [
+  "futures-v0_3",
+] }
 tokio = { workspace = true, features = ["full"], optional = true }
 
 [target.'cfg(target_os = "linux")'.dependencies]
@@ -62,15 +65,18 @@ command-fds = "0.2.1"
 [target.'cfg(windows)'.dependencies]
 mio = { version = "0.8", features = ["os-ext", "os-poll"] }
 os_pipe.workspace = true
-windows-sys = {version = "0.48.0", features = [
+windows-sys = { version = "0.48.0", features = [
   "Win32_Foundation",
   "Win32_System_WindowsProgramming",
   "Win32_System_Console",
   "Win32_System_Pipes",
   "Win32_Security",
   "Win32_Storage_FileSystem",
   "Win32_System_Threading",
-  ]}
+] }
 
 [dev-dependencies]
 tempfile = "3.6"
+
+[package.metadata.docs.rs]
+features = ["docs"]
diff --git a/crates/shim/README.md b/crates/shim/README.md
@@ -10,6 +10,22 @@ Rust crate to ease runtime v2 shim implementation.
 It replicates same [shim.Run](https://github.com/containerd/containerd/blob/dbef1d56d7ebc05bc4553d72c419ed5ce025b05d/runtime/v2/example/cmd/main.go)
 API offered by containerd's shim v2 runtime implementation written in Go.
 
+## Runtime
+
+Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd.
+The shim API is minimal and scoped to the execution lifecycle of a container.
+
+This crate simplifies shim v2 runtime development for containerd. It handles common tasks such
+as command line parsing, setting up shim's TTRPC server, logging, events, etc.
+
+Clients are expected to implement [Shim] and [Task] traits with task handling routines.
+This generally replicates same API as in Go [version](https://github.com/containerd/containerd/blob/main/runtime/v2/example/cmd/main.go).
+
+Once implemented, shim's bootstrap code is as easy as:
+```rust
+shim::run::<Service>("io.containerd.empty.v1")
+```
+
 ## Look and feel
 
 The API is very similar to the one offered by Go version:
@@ -73,7 +89,6 @@ impl shim::Task for Service {
 fn main() {
     shim::run::<Service>("io.containerd.empty.v1")
 }
-
 ```
 
 ## How to use with containerd
@@ -97,7 +112,7 @@ $ sudo ctr run --rm --runtime ./target/debug/examples/skeleton docker.io/library
 
 Or manually:
 
-```
+```bash
 $ touch log
 
 # Run containerd in background

diff --git a/crates/shim/src/lib.rs b/crates/shim/src/lib.rs
@@ -14,23 +14,7 @@
    limitations under the License.
 */
 
-//! A library to implement custom runtime v2 shims for containerd.
-//!
-//! # Runtime
-//! Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd.
-//! The shim API is minimal and scoped to the execution lifecycle of a container.
-//!
-//! This crate simplifies shim v2 runtime development for containerd. It handles common tasks such
-//! as command line parsing, setting up shim's TTRPC server, logging, events, etc.
-//!
-//! Clients are expected to implement [Shim] and [Task] traits with task handling routines.
-//! This generally replicates same API as in Go [version](https://github.com/containerd/containerd/blob/main/runtime/v2/example/cmd/main.go).
-//!
-//! Once implemented, shim's bootstrap code is as easy as:
-//! ```text
-//! shim::run::<Service>("io.containerd.empty.v1")
-//! ```
-//!
+#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
 
 use std::{collections::hash_map::DefaultHasher, fs::File, hash::Hasher, path::PathBuf};
 #[cfg(unix)]

diff --git a/crates/snapshots/Cargo.toml b/crates/snapshots/Cargo.toml
@@ -14,6 +14,9 @@ license.workspace = true
 repository.workspace = true
 homepage.workspace = true
 
+[features]
+docs = []
+
 [dependencies]
 async-stream = "0.3.3"
 futures.workspace = true
@@ -34,3 +37,6 @@ simple_logger = { version = "4.0", default-features = false }
 
 [build-dependencies]
 tonic-build.workspace = true
+
+[package.metadata.docs.rs]
+features = ["docs"]
diff --git a/crates/snapshots/src/lib.rs b/crates/snapshots/src/lib.rs
@@ -14,41 +14,7 @@
    limitations under the License.
 */
 
-//! Remote snapshotter extension for containerd.
-//!
-//! Snapshots crate implements containerd's proxy plugin for snapshotting. It aims hide the underlying
-//! complexity of GRPC interfaces, streaming and request/response conversions and provide one
-//! [crate::Snapshotter] trait to implement.
-//!
-//! # Proxy plugins
-//! A proxy plugin is configured using containerd's config file and will be loaded alongside the
-//! internal plugins when containerd is started. These plugins are connected to containerd using a
-//! local socket serving one of containerd's GRPC API services. Each plugin is configured with a
-//! type and name just as internal plugins are.
-//!
-//! # How to use from containerd
-//! Add the following to containerd's configuration file:
-//! ```toml
-//! [proxy_plugins]
-//!   [proxy_plugins.custom]
-//!     type = "snapshot"
-//!     address = "/tmp/snap2.sock"
-//! ```
-//! Start containerd daemon:
-//! ```bash
-//! containerd --config /path/config.toml
-//! ```
-//!
-//! Run remote snapshotter instance:
-//! ```bash
-//! $ cargo run --example snapshotter /tmp/snap2.sock
-//! ```
-//! Now specify `custom` snapshotter when pulling an image with `ctr`:
-//! ```bash
-//! $ ctr i pull --snapshotter custom docker.io/library/hello-world:latest
-//! ```
-//!
-
+#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]
 // No way to derive Eq with tonic :(
 // See https://github.com/hyperium/tonic/issues/1056
 #![allow(clippy::derive_partial_eq_without_eq)]