Switch back to pure Zig Autodoc for documentation

  * Remove hybrid MkDocs setup
  * Restore project documentation to src/lib.zig doc comments
  * Update build.zig to use standard addLibrary pattern for docs
  * Simplify GH Pages workflow to use purely Zig

Author: ananthb

.github/workflows/deploy-docs.yml

@@ -28,19 +28,15 @@ jobs:
         uses: DeterminateSystems/magic-nix-cache-action@main
 
       - name: Generate Documentation
-        run: |
-          nix develop .#default --command mkdocs build
-          nix develop .#default --command zig build docs -p site
-          # The docs step in build.zig installs to <prefix>/docs, so we move it to <prefix>/api
-          mv site/docs site/api
+        run: nix develop .#default --command zig build docs -p zig-out
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: site
+          path: zig-out/docs
 
   deploy:
     environment:

build.zig

@@ -115,14 +115,16 @@ pub fn build(b: *std.Build) void {
     valgrind_run.addArtifactArg(tests);
     valgrind_step.dependOn(&valgrind_run.step);
 
+    // Docs step
     const docs_step = b.step("docs", "Generate API documentation");
 
-    const docs_test = b.addTest(.{
+    const docs_lib = b.addLibrary(.{
+        .name = "runz",
         .root_module = runz_module,
     });
 
     const docs_install = b.addInstallDirectory(.{
-        .source_dir = docs_test.getEmittedDocs(),
+        .source_dir = docs_lib.getEmittedDocs(),
         .install_dir = .prefix,
         .install_subdir = "docs",
     });

docs/index.md

@@ -1,8 +1,49 @@
-//! runz - OCI container runtime and library
+//! # runz - OCI Container Runtime & Library
 //!
-//! Container runtime with image pulling, layer extraction,
-//! namespace isolation, cgroups, capabilities, networking,
-//! and OCI runtime spec support.
+//! A high-performance, daemonless OCI container runtime and library written in Zig.
+//!
+//! ## Technical Specifications
+//! - **OCI Standards**: Implements the OCI runtime and image specifications.
+//! - **Zig Implementation**: predictable performance and memory safety.
+//! - **Daemonless**: Executes containers without a background process.
+//! - **Library & CLI**: Provides a standalone binary and a Zig module for integration.
+//!
+//! ## Installation
+//!
+//! ### Prerequisites
+//! - Zig 0.13.0 or later
+//! - Linux (for runtime features)
+//!
+//! ### Using as a Library
+//! Add `runz` to your `build.zig.zon`:
+//! ```zig
+//! .dependencies = .{
+//!     .runz = .{
+//!         .url = "git+https://github.com/ananthb/runz",
+//!         .hash = "...",
+//!     },
+//! },
+//! ```
+//!
+//! ## Basic Usage
+//!
+//! ### Pulling an Image
+//! ```zig
+//! const std = @import("std");
+//! const runz = @import("runz");
+//!
+//! pub fn main() !void {
+//!     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+//!     const allocator = gpa.allocator();
+//!     defer _ = gpa.deinit();
+//!
+//!     var client = try runz.registry.RegistryClient.init(allocator, "registry-1.docker.io");
+//!     defer client.deinit();
+//!
+//!     try client.ensureAuth("library/alpine");
+//!     const manifest = try client.fetchManifest("library/alpine", "latest", null);
+//! }
+//! ```
 
 /// OCI spec types (image, runtime, distribution)
 pub const spec = @import("ocispec");
@@ -63,7 +104,3 @@ pub const annotations = @import("annotations.zig");
 
 /// Linux-specific utilities (namespaces, mounts, seccomp, cgroups, capabilities)
 pub const linux_util = @import("linux.zig");
-
-test "docs" {
-    _ = @import("std").testing;
-}