Skip to content

Simplify doc management and update READMEs #208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mxpv merged 3 commits into from
Oct 4, 2023
Merged

Simplify doc management and update READMEs #208

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e9910f3
Simplify doc management
mxpv Sep 28, 2023
8555774
Make examples compilable
mxpv Sep 28, 2023
7b69bd6
Enable docs feature on CI
mxpv Oct 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions crates/client/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
14 changes: 9 additions & 5 deletions crates/client/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,15 @@ This crate implements a GRPC client to query containerd APIs.
## Example

```rust
// Launch containerd at /run/containerd/containerd.sock
let channel = connect("/run/containerd/containerd.sock").await?;
use containerd_client::{connect, services::v1::version_client::VersionClient};

let mut client = VersionClient::new(channel);
let resp = client.version(()).await?;
async fn query_version() {
// Launch containerd at /run/containerd/containerd.sock
let channel = connect("/run/containerd/containerd.sock").await.unwrap();

println!("Response: {:?}", resp.get_ref());
let mut client = VersionClient::new(channel);
let resp = client.version(()).await.unwrap();

println!("Response: {:?}", resp.get_ref());
}
```
3 changes: 1 addition & 2 deletions crates/client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,11 @@
limitations under the License.
*/

#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))]

@jsturtevant jsturtevant Oct 4, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does this need the `//!`` so it formats properly?

@mxpv mxpv Oct 4, 2023

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, we can include markdown directly here.
You can verify the final result with:

cargo doc --no-deps --features docs --open

@jsturtevant jsturtevant Oct 4, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cool!

// 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.
Expand Down
8 changes: 7 additions & 1 deletion crates/logging/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ name = "containerd-shim-logging"
version = "0.1.1"
authors = [
"Maksym Pavlenko <pavlenko.maksym@gmail.com>",
"The containerd Authors"
"The containerd Authors",
]
description = "Logger extension for containerd v2 runtime"
keywords = ["containerd", "shim", "containers"]
Expand All @@ -13,3 +13,9 @@ edition.workspace = true
license.workspace = true
repository.workspace = true
homepage.workspace = true

[features]
docs = []

[package.metadata.docs.rs]
features = ["docs"]
9 changes: 1 addition & 8 deletions crates/logging/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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};

Expand Down
11 changes: 6 additions & 5 deletions crates/runc/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,7 @@
[package]
name = "runc"
version = "0.2.0"
authors = [
"Yuna Tomida <ytomida.mmm@gmail.com>",
"The containerd Authors",
]
authors = ["Yuna Tomida <ytomida.mmm@gmail.com>", "The containerd Authors"]
description = "A crate for consuming the runc binary in your Rust applications"
keywords = ["containerd", "containers", "runc"]
categories = ["api-bindings", "asynchronous"]
Expand All @@ -16,6 +13,7 @@ homepage.workspace = true

[features]
async = ["tokio", "async-trait", "futures", "tokio-pipe"]
docs = []

[dependencies]
libc.workspace = true
Expand All @@ -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"]
8 changes: 3 additions & 5 deletions crates/runc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,10 @@ You can build runc client with `RuncConfig` in method chaining style.
Call `build()` or `build_async()` to get client.
Note that async client depends on [tokio](https://github.com/tokio-rs/tokio), then please use it on tokio runtime.

```rust
use runc;

```rust,ignore
#[tokio::main]
async fn main() {
let config = runc::Config::new()
let config = runc::GlobalOpts::new()
.root("./new_root")
.debug(false)
.log("/path/to/logfile.json")
Expand All @@ -45,4 +43,4 @@ async fn main() {
- delete
- Exec is **not** available in `RuncAsyncClient` now.
- Console utilites are **not** available
- see [Go version](https://github.com/containerd/go-runc/blob/main/console.go)
- see [Go version](https://github.com/containerd/go-runc/blob/main/console.go)
2 changes: 2 additions & 0 deletions crates/runc/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::{
Expand Down
8 changes: 7 additions & 1 deletion crates/shim-protos/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ homepage.workspace = true
default = []
async = ["ttrpc/async", "async-trait"]
sandbox = []
docs = []

[[example]]
name = "shim-proto-server"
Expand Down Expand Up @@ -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"]
31 changes: 24 additions & 7 deletions crates/shim-protos/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -23,18 +38,20 @@ containerd-shim-protos = "0.4"

Basic client code looks as follows:

```rust
let client = client::Client::connect(socket_path)?;
```rust,no_run
use containerd_shim_protos as client;

let client = client::Client::connect("unix:///containerd-shim/shim.sock").expect("Failed to connect to shim");
let task_client = client::TaskClient::new(client);

let context = client::ttrpc::context::with_timeout(0);

let req = client::api::ConnectRequest {
id: pid,
id: String::from("1"),
..Default::default()
};

let resp = task_client.connect(context, &req)?;
let resp = task_client.connect(context, &req).expect("Connect request failed");
```

## Example
Expand Down
47 changes: 1 addition & 46 deletions crates/shim-protos/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
16 changes: 11 additions & 5 deletions crates/shim/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ async = [
"signal-hook-tokio",
"tokio",
]
docs = []

[[example]]
name = "skeleton_async"
Expand All @@ -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"
Expand All @@ -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]
Expand All @@ -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"]
Loading