Merge pull request #98 from floooh/docs-build-step

Move doc generation entirely into Zig code...

.github/workflows/docs.yml

@@ -12,13 +12,12 @@ jobs:
         with:
             version: master
       - name: gen-docs
-        run: ./gendocs.sh
+        run: zig build docs
       - name: upload-artifact
         uses: actions/upload-artifact@main
         with:
           name: sokol-zig-docs
-          path: docs
-          retention-days: 1
+          path: zig-out/docs
   deploy:
     needs: build
     runs-on: ubuntu-latest

.gitignore

@@ -1,7 +1,5 @@
 .vscode/
-docs
+.DS_Store
 zig-*/
 .zig-*/
 NUL
-*.a
-*.a.o

build.zig

@@ -79,6 +79,8 @@ pub fn build(b: *Build) !void {
 
     // a manually invoked build step to recompile shaders via sokol-shdc
     buildShaders(b, target);
+    // a manually invoked build step to build auto-docs
+    buildDocs(b, target);
 }
 
 // build one of the examples
@@ -516,3 +518,37 @@ fn buildShaders(b: *Build, target: Build.ResolvedTarget) void {
         shdc_step.dependOn(&cmd.step);
     }
 }
+
+fn buildDocs(b: *Build, target: Build.ResolvedTarget) void {
+    const lib = b.addStaticLibrary(.{
+        .name = "sokol",
+        .root_source_file = b.path("src/sokol/sokol.zig"),
+        .target = target,
+        .optimize = .Debug,
+    });
+    // need to invoke an external tool to inject custom functionality into a build step:
+    const tool = b.addExecutable(.{
+        .name = "fixdoctar",
+        .root_source_file = b.path("tools/fixdoctar.zig"),
+        .target = b.graph.host,
+    });
+    const tool_step = b.addRunArtifact(tool);
+    tool_step.addArgs(&.{ "--prefix", "sokol", "--input" });
+    tool_step.addDirectoryArg(lib.getEmittedDocs());
+    tool_step.addArg("--output");
+    const sources_tar = tool_step.addOutputFileArg("sources.tar");
+    tool_step.step.dependOn(&lib.step);
+
+    // install doc-gen output and the smaller sources.tar on top
+    const install_docs = b.addInstallDirectory(.{
+        .source_dir = lib.getEmittedDocs(),
+        .install_dir = .prefix,
+        .install_subdir = "docs",
+    });
+    install_docs.step.dependOn(&tool_step.step);
+    const overwrite_sources_tar = b.addInstallFile(sources_tar, "docs/sources.tar");
+    overwrite_sources_tar.step.dependOn(&install_docs.step);
+
+    const doc_step = b.step("docs", "Build documentation");
+    doc_step.dependOn(&overwrite_sources_tar.step);
+}

tools/fixdoctar.zig

@@ -0,0 +1,62 @@
+//! repackage the autodocs sources.tar to only contain sokol sources
+//! (which reduces the size from 13 MBytes to abour 500 KBytes)
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+
+pub fn main() !void {
+    var arena_state = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+
+    // parse args
+    const prefix = try arg(arena, "--prefix");
+    const input_dir = try arg(arena, "--input");
+    const output_path = try arg(arena, "--output");
+
+    // iterate over sources.tar file, find relevant files and write to output tar file
+    const inp_path = try std.fs.path.join(arena, &.{ input_dir, "sources.tar" });
+    const inp_file = std.fs.openFileAbsolute(inp_path, .{}) catch |err| {
+        fatal("failed to open input file '{s}' with {}", .{ inp_path, err });
+    };
+    defer inp_file.close();
+    const outp_file = std.fs.createFileAbsolute(output_path, .{}) catch |err| {
+        fatal("failed to open output file '{s}' with {}", .{ output_path, err });
+    };
+    defer outp_file.close();
+
+    var tar_writer = std.tar.writer(outp_file.writer());
+    var file_name_buffer: [1024]u8 = undefined;
+    var link_name_buffer: [1024]u8 = undefined;
+    var iter = std.tar.iterator(inp_file.reader(), .{
+        .file_name_buffer = &file_name_buffer,
+        .link_name_buffer = &link_name_buffer,
+    });
+    while (try iter.next()) |tar_item| {
+        switch (tar_item.kind) {
+            .file => {
+                if (std.mem.startsWith(u8, tar_item.name, prefix)) {
+                    try tar_writer.writeFileStream(tar_item.name, tar_item.size, tar_item.reader(), .{ .mode = tar_item.mode });
+                }
+            },
+            else => continue,
+        }
+    }
+    return std.process.cleanExit();
+}
+
+fn fatal(comptime fmt: []const u8, args: anytype) noreturn {
+    std.log.err(fmt, args);
+    std.process.exit(5);
+}
+
+fn arg(allocator: Allocator, key: []const u8) ![]const u8 {
+    var arg_iter = try std.process.argsWithAllocator(allocator);
+    defer arg_iter.deinit();
+    while (arg_iter.next()) |cur| {
+        if (std.mem.eql(u8, key, cur)) {
+            const val = arg_iter.next() orelse fatal("expected arg after {s}", .{key});
+            return allocator.dupe(u8, val);
+        }
+    }
+    fatal("expected arg {s}", .{key});
+}