feat: online docs

.github/workflows/docs.yaml

@@ -0,0 +1,45 @@
+# https://github.com/actions/starter-workflows/blob/main/pages/static.yml
+on:
+  push:
+    branches: ["master"]
+  workflow_dispatch:
+
+permissions:
+  pages: write
+  contents: read
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+      - name: Setup Zig
+        uses: goto-bus-stop/setup-zig@v2
+      - name: Generate docs
+        run: |
+          zig build docs
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          # Upload entire repository
+          path: zig-out/docs/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3

build.zig

@@ -38,6 +38,16 @@ pub fn build(b: *std.Build) void {
     // running `zig build`).
     b.installArtifact(lib);
 
+    // Docs
+    const docs_step = b.step("docs", "Emit docs");
+    const docs_install = b.addInstallDirectory(.{
+        .source_dir = lib.getEmittedDocs(),
+        .install_dir = .prefix,
+        .install_subdir = "docs",
+    });
+    docs_step.dependOn(&docs_install.step);
+    b.default_step.dependOn(docs_step);
+
     const mod = b.addModule("cron", .{
         .source_file = .{ .path = "src/lib.zig" },
         .dependencies = &.{.{ .name = "datetime", .module = datetime_module }},

src/cron.zig

@@ -13,19 +13,57 @@ const BitSet = std.bit_set.IntegerBitSet(130);
 
 const LEN = 48;
 
+/// A sturct for parsing cron strings and calculating next and previous execution datetimes.
+/// Example:
+/// ```zig
+/// const std = @import("std");
+/// const Cron = @import("cron").Cron;
+/// const datetime = @import("datetime").datetime;
+///
+/// fn job1(i: usize) !void {
+///     const now = datetime.Datetime.now();
+///
+///     var buf: [64]u8 = undefined;
+///     const dt_str = try now.formatISO8601Buf(&buf, false);
+///     std.log.info("{s} {d}th execution", .{ dt_str, i });
+/// }
+///
+/// pub fn main() !void {
+///     var c = Cron.init();
+///     // At every minute.
+///     try c.parse("*/1 * * * *");
+///
+///     for (0..5) |i| {
+///         const now = datetime.Datetime.now();
+///
+///         // Get the next run time
+///         const next_dt = try c.next(now);
+///         const duration = next_dt.sub(now);
+///         // convert to nanoseconds
+///         const nanos = duration.totalSeconds() * std.time.ns_per_s + duration.nanoseconds;
+///
+///         // wait next
+///         std.time.sleep(@intCast(nanos));
+///
+///         try job1(i + 1);
+///     }
+/// }
+/// ```
 pub const Cron = struct {
     buf: [LEN]u8,
     expr: CronExpr,
 
     const Self = @This();
 
+    /// Initialize cron
     pub fn init() Self {
         return Self{
             .buf = undefined,
             .expr = undefined,
         };
     }
 
+    /// Parse cron expression
     pub fn parse(self: *Self, input: []const u8) !void {
         var buf_: [LEN]u8 = undefined;
         const lower_input = std.ascii.lowerString(&buf_, input);
@@ -156,6 +194,7 @@ pub const Cron = struct {
         unreachable;
     }
 
+    /// Calculates and returns the datetime of the next scheduled execution based on the parsed cron schedule and the provided starting datetime.
     pub fn next(self: *Self, now: datetime.Datetime) !datetime.Datetime {
         // reset nanoseconds
         var future = now.shift(.{ .nanoseconds = -@as(i32, @intCast(now.time.nanosecond)) }).shiftSeconds(1);
@@ -221,6 +260,7 @@ pub const Cron = struct {
         return future;
     }
 
+    /// Calculates and returns the datetime of the most recent past scheduled execution based on the parsed cron schedule and the provided starting datetime.
     pub fn previous(self: *Self, now: datetime.Datetime) !datetime.Datetime {
         // reset nanoseconds
         var future = now.shift(.{ .nanoseconds = -@as(i32, @intCast(now.time.nanosecond)) }).shiftSeconds(-1);