clients: bring back testing of READMEs on CI

Move logic from docs_generate utility into `scripts -- ci` workflow, so
that it gets executed by CI naturally. Along the way, cleanup code a
bit:

* use rely on `shell.zig` rather than `shutil.zig`, remove the latter.
* merge `Generator` and `Markdown` writer into a single `Context`
  struct. There might be some finer grained factoring here, but we don't
  use markdown-writing capabilities elsewhere, so a single grab bag of
  stuff feels simpler.
* pull the overall control flow for reading&updating files into a
  top-level function.
* remove helper functions for generating common parts between main &
  sample readmes --- the "common" parts differ more than they are the
  same, it's more readable to copy the relevant paragraphs twice
* use code blocks to delimit markdown sections. This surfaces one wrong
  header even!

Author: matklad

Diff for: build.zig

@@ -394,12 +394,6 @@ pub fn build(b: *std.Build) !void {
             git_clone_tracy,
             tracer_backend,
         );
-        client_docs(
-            b.allocator,
-            b,
-            mode,
-            target,
-        );
     }
 
     {
@@ -1036,81 +1030,6 @@ fn c_client_sample(
     c_sample_build.dependOn(&install_step.step);
 }
 
-// Allows a build step to run the command it builds after it builds it if the user passes --.
-// e.g.: ./zig/zig build docs_generate --
-// Whereas `./zig/zig build docs_generate` would not run the command.
-fn maybe_execute(
-    b: *std.Build,
-    allocator: std.mem.Allocator,
-    top_level_step: *std.Build.Step,
-    install_step: *std.Build.Step.InstallArtifact,
-    binary_name: []const u8,
-) void {
-    var to_run = std.ArrayList([]const u8).init(allocator);
-    defer to_run.deinit();
-
-    const sep = if (builtin.os.tag == .windows) "\\" else "/";
-    const ext = if (builtin.os.tag == .windows) ".exe" else "";
-    to_run.append(
-        std.fmt.allocPrint(
-            allocator,
-            ".{s}zig-out{s}bin{s}{s}{s}",
-            .{
-                sep,
-                sep,
-                sep,
-                binary_name,
-                ext,
-            },
-        ) catch unreachable,
-    ) catch unreachable;
-
-    var args = std.process.argsWithAllocator(allocator) catch unreachable;
-    defer args.deinit();
-
-    var build_and_run = false;
-    while (args.next()) |arg| {
-        if (std.mem.eql(u8, arg, "--")) {
-            build_and_run = true;
-            continue;
-        }
-
-        if (build_and_run) {
-            to_run.append(arg) catch unreachable;
-        }
-    }
-
-    if (build_and_run) {
-        const run = b.addSystemCommand(to_run.items);
-        run.step.dependOn(&install_step.step);
-        top_level_step.dependOn(&run.step);
-    }
-}
-
-// See src/clients/README.md for documentation.
-fn client_docs(
-    allocator: std.mem.Allocator,
-    b: *std.Build,
-    mode: Mode,
-    target: CrossTarget,
-) void {
-    const binary = b.addExecutable(.{
-        .name = "client_docs",
-        .root_source_file = .{ .path = "src/clients/docs_generate.zig" },
-        .target = target,
-        .optimize = mode,
-        .main_pkg_path = .{ .path = "src" },
-    });
-
-    const client_docs_build = b.step("client_docs", "Generate documentation for a client library");
-    client_docs_build.dependOn(&binary.step);
-
-    const install_step = b.addInstallArtifact(binary, .{});
-    client_docs_build.dependOn(&install_step.step);
-
-    maybe_execute(b, allocator, client_docs_build, install_step, "client_docs");
-}
-
 /// Steps which unconditionally fails with a message.
 ///
 /// This is useful for cases where at configuration time you can determine that a certain step

Diff for: src/clients/.gitignore

@@ -1,2 +1 @@
 *.o
-docs_generate

Diff for: src/clients/README.md

@@ -3,13 +3,13 @@
 ## Documentation
 
 Documentation for clients (i.e. client `README.md`s) are generated
-from [docs_generate.zig](./docs_generate.zig).
+from [../scripts/client_readmes.zig](../scripts/client_readmes.zig).
 
 Each client implements the `Docs` struct from
 [docs_types.zig](./docs_types.zig).
 
 The template for the README is in code in
-[docs_generate.zig](./docs_generate.zig).
+[../scripts/client_readmes.zig](../scripts/client_readmes.zig).
 
 Existing `Docs` struct implementations are in:
 
@@ -34,21 +34,15 @@ script on Windows.
 To build and run the client docs generator:
 
 ```console
-./zig/zig build client_docs --
+./zig/zig build scripts -- ci
 ```
 
-Note: Omitting the `--` will only build, not run the client_docs script.
-
 ### Just one language
 
 To run the generator only for a certain language (defined by `.markdown_name`):
 
 ```console
-./zig/zig build client_docs -- --language=node
-```
-
-```console
-./zig/zig build client_docs -- --language=node,go
+./zig/zig build scripts -- ci --language=go
 ```
 
 Docs are only regenerated/modified when there would be a diff so the