feat: Add cargo-doc-live

doc/cargo-doc-live.md

@@ -0,0 +1,40 @@
+# cargo-doc-live
+
+[cargo-doc-live] is live server version of `cargo doc`.
+
+{#start}
+
+## Getting started
+
+```nix
+# In `perSystem.process-compose.<name>`
+{
+  services.cargo-doc-live."cargo-doc-live1".enable = true;
+}
+```
+
+{#port}
+
+### The port for `cargo doc`
+
+```nix
+{
+  services.cargo-doc-live."cargo-doc-live1" = {
+    enable = true;
+    port = 8080;
+  };
+}
+```
+
+{#crateName}
+
+### The crate to use when opening docs in browser
+
+```nix
+{
+  services.cargo-doc-live."cargo-doc-live1" = {
+    enable = true;
+    crateName = "chrono";
+  };
+}
+```

doc/services.md

@@ -4,7 +4,7 @@ short-title: Services
 
 # Supported services
 
->[!warning] WIP
+> [!warning] WIP
 > Documentation for the services is still in progress. Please refer to [this issue][gh] for progress.
 
 - [[apache-kafka]]#
@@ -25,5 +25,6 @@ short-title: Services
 - [[prometheus]]#
 - [[cassandra]]#
 - [[weaviate]]#
+- [[cargo-doc-live]]#
 
 [gh]: https://github.com/juspay/services-flake/issues/132

nix/cargo-doc-live.nix

@@ -0,0 +1,69 @@
+{ pkgs, lib, name, config, ... }:
+let
+  inherit (lib) types;
+in
+{
+  options = {
+    enable = lib.mkEnableOption name;
+
+    port = lib.mkOption {
+      type = types.port;
+      description = "The port for 'cargo doc'";
+      default = 8008;
+    };
+
+    crateName = lib.mkOption {
+      type = types.str;
+      description = "The crate to use when opening docs in browser";
+      default = builtins.replaceStrings [ "-" ] [ "_" ]
+        ((lib.trivial.importTOML ./Cargo.toml).package.name);
+      defaultText = "The crate name is derived from the Cargo.toml file";
+    };
+
+    outputs.settings = lib.mkOption {
+      type = types.deferredModule;
+      internal = true;
+      readOnly = true;
+      default = {
+        processes =
+          let
+            browser-sync = lib.getExe pkgs.nodePackages.browser-sync;
+            cargo-watch = lib.getExe pkgs.cargo-watch;
+            cargo = lib.getExe pkgs.cargo;
+          in
+          {
+            "${name}-cargo-doc" = {
+              command = builtins.toString (pkgs.writeShellScript "cargo-doc" ''
+                run-cargo-doc() {
+                  ${cargo} doc --document-private-items --all-features
+                  ${browser-sync} reload --port ${toString config.port}  # Trigger reload in browser
+                }; export -f run-cargo-doc
+                ${cargo-watch} watch -s run-cargo-doc
+              '');
+
+              readiness_probe = {
+                period_seconds = 1;
+                failure_threshold = 100000; # 'cargo doc' can take quite a while.
+                exec.command = ''
+                  # Wait for the first 'cargo doc' to have completed.
+                  # We'll use this state to block browser-sync from starting
+                  # and opening the URL in the browser.
+                  ls target/doc/${config.crateName}/index.html
+                '';
+              };
+              namespace = name;
+              availability.restart = "on_failure";
+            };
+            "${name}-browser-sync" = {
+              command = ''
+                ${browser-sync} start --port ${toString config.port} --ss target/doc -s target/doc \
+                  --startPath /${config.crateName}/
+              '';
+              namespace = name;
+              depends_on."${name}-cargo-doc".condition = "process_healthy";
+            };
+          };
+      };
+    };
+  };
+}

nix/cargo-doc-live_test.nix

@@ -0,0 +1,18 @@
+{ pkgs, ... }: {
+  services.cargo-doc-live."cargo-doc-live1" = {
+    enable = true;
+    crateName = "simple";
+  };
+
+  settings.processes.test =
+    {
+      command = pkgs.writeShellApplication {
+        runtimeInputs = [ pkgs.curl ];
+        text = ''
+          curl http://127.0.0.1:8008/simple
+        '';
+        name = "cargo-doc-live-test";
+      };
+      depends_on."cargo-doc-live1".condition = "process_healthy";
+    };
+}

nix/default.nix

@@ -22,5 +22,6 @@ in
     ./tempo.nix
     ./weaviate.nix
     ./searxng.nix
+    ./cargo-doc-live.nix
   ];
 }

test/flake.nix

@@ -49,6 +49,7 @@
             "${inputs.services-flake}/nix/cassandra_test.nix"
             "${inputs.services-flake}/nix/tempo_test.nix"
             "${inputs.services-flake}/nix/weaviate_test.nix"
+            "${inputs.services-flake}/nix/cargo-doc-live_test.nix"
           ] ++ lib.optionals pkgs.stdenv.isLinux [
             # Broken on Darwin: https://github.com/NixOS/nixpkgs/issues/316954
             "${inputs.services-flake}/nix/grafana_test.nix"