Merge pull request #85 from cpuguy83/docs

Fix code docs

Author: cpuguy83

.github/workflows/ci.yml

@@ -32,6 +32,8 @@ jobs:
         with:
           command: build
           args: --all --verbose
+      - name: Validate docs
+        run: ./scripts/validate-docs.sh
       - name: Run tests
         uses: actions-rs/cargo@v1
         with:

Cargo.lock

@@ -4,7 +4,7 @@ description = "Library for building containerd shims for wasm"
 version = "0.1.1"
 edition.workspace = true
 license.workspace = true
-readme.workspace = true
+readme = "README.md"
 homepage.workspace = true
 repository.workspace = true
 
@@ -42,3 +42,4 @@ rand = "0.8"
 [features]
 default = []
 generate_bindings = ["ttrpc-codegen"]
+generate_doc = []

crates/containerd-shim-wasm/Cargo.toml

@@ -0,0 +1,40 @@
+![runwasi logo](../../art/logo/runwasi_logo_icon.svg)
+
+# containerd-shim-wasm
+
+A library to help build containerd shims for wasm workloads.
+
+## Usage
+
+```rust
+use containerd_shim as shim;
+use containerd_shim_wasm::sandbox::{ShimCli, Instance, Nop}
+
+fn main() {
+    shim::run::<ShimCli<Nop>>("io.containerd.nop.v1", opts);
+}
+```
+
+The above example uses the built-in `Nop` instance which does nothing.
+You can build your own instance by implementing the `Instance` trait.
+
+```rust
+use containerd_shim as shim;
+use containerd_shim_wasm::sandbox::{ShimCli, Instance}
+
+struct MyInstance {
+ // ...
+}
+
+impl Instance for MyInstance {
+    // ...
+}
+
+fn main() {
+    shim::run::<ShimCli<MyInstance>>("io.containerd.myshim.v1", opts);
+}
+```
+
+containerd expects the shim binary to be installed into `$PATH` (as seen by the containerd process) with a binary name like `containerd-shim-myshim-v1` which maps to the `io.containerd.myshim.v1` runtime which would need to be configured in containerd. It (containerd) also supports specifying a path to the shim binary but needs to be configured to do so.
+
+This crate is not tied to any specific wasm engine.

crates/containerd-shim-wasm/README.md

@@ -5,8 +5,19 @@ use std::fs;
 use ttrpc_codegen::{Codegen, ProtobufCustomize};
 
 #[cfg(not(feature = "generate_bindings"))]
+#[cfg(not(feature = "generate_doc"))]
 fn main() {}
 
+#[cfg(feature = "generate_doc")]
+fn main() {
+    use std::io::Write;
+    println!("cargo:rerun-if-changed=doc");
+    println!("cargo:rerun-if-missing=README.md");
+    let mut f = std::fs::File::create("README.md").unwrap();
+    f.write_all(include_bytes!("doc/header.md")).unwrap();
+    f.write_all(include_bytes!("doc/doc.md")).unwrap();
+}
+
 #[cfg(feature = "generate_bindings")]
 fn main() {
     println!("cargo:rerun-if-changed=protos");

crates/containerd-shim-wasm/build.rs

@@ -0,0 +1,36 @@
+A library to help build containerd shims for wasm workloads.
+
+## Usage
+
+```rust
+use containerd_shim as shim;
+use containerd_shim_wasm::sandbox::{ShimCli, Instance, Nop}
+
+fn main() {
+    shim::run::<ShimCli<Nop>>("io.containerd.nop.v1", opts);
+}
+```
+
+The above example uses the built-in `Nop` instance which does nothing.
+You can build your own instance by implementing the `Instance` trait.
+
+```rust
+use containerd_shim as shim;
+use containerd_shim_wasm::sandbox::{ShimCli, Instance}
+
+struct MyInstance {
+ // ...
+}
+
+impl Instance for MyInstance {
+    // ...
+}
+
+fn main() {
+    shim::run::<ShimCli<MyInstance>>("io.containerd.myshim.v1", opts);
+}
+```
+
+containerd expects the shim binary to be installed into `$PATH` (as seen by the containerd process) with a binary name like `containerd-shim-myshim-v1` which maps to the `io.containerd.myshim.v1` runtime which would need to be configured in containerd. It (containerd) also supports specifying a path to the shim binary but needs to be configured to do so.
+
+This crate is not tied to any specific wasm engine.

crates/containerd-shim-wasm/doc/doc.md

@@ -0,0 +1,4 @@
+![runwasi logo](../../art/logo/runwasi_logo_icon.svg)
+
+# containerd-shim-wasm
+

crates/containerd-shim-wasm/doc/header.md

@@ -1,2 +1,8 @@
+#![doc = include_str!("../doc/doc.md")]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/containerd/runwasi/e251de3307bbdc8bf3229020ea2ae2711f31aafa/art/logo/runwasi_logo_icon.svg"
+)]
+
 pub mod sandbox;
+
 pub mod services;

crates/containerd-shim-wasm/src/lib.rs

@@ -1,3 +1,5 @@
+//! Module for interacting with and applying OCI specs for cgroups v1.
+
 use super::super::{Error, Result};
 use super::{
     ensure_write_file, find_cgroup_mounts, list_cgroup_controllers, new_mount_iter, safe_join,
@@ -11,6 +13,7 @@ use std::io::prelude::Write;
 use std::ops::Not;
 use std::path::PathBuf;
 
+// Manager for a cgroup v1 hierarchy.
 pub struct CgroupV1 {
     path: PathBuf,
     controllers: HashMap<String, PathBuf>,

crates/containerd-shim-wasm/src/sandbox/cgroups/cgroupv1.rs

@@ -1,3 +1,5 @@
+//! Module for interacting with and applying OCI specs for cgroups v2.
+
 use super::super::{Error, Result};
 use super::RawFD;
 use super::{
@@ -11,6 +13,7 @@ use std::fs;
 use std::ops::Not;
 use std::path::PathBuf;
 
+/// Manages a cgroup v2 heirarchy.
 pub struct CgroupV2 {
     base: PathBuf,
     path: PathBuf,