feat: Add cargo-doc-live

.gitignore

@@ -8,5 +8,6 @@
 /example/share-services/pgweb/data/
 /example/simple/data/
 /example/grafana-tempo/data/
+/example/cargo-doc-live/target
 
 /.pre-commit-config.yaml

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

example/cargo-doc-live/Cargo.toml

@@ -0,0 +1,2 @@
+[package]
+name = "test"

example/cargo-doc-live/flake.nix

@@ -0,0 +1,44 @@
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    systems.url = "github:nix-systems/default";
+    process-compose-flake.url = "github:Platonic-Systems/process-compose-flake";
+    services-flake.url = "github:juspay/services-flake";
+  };
+  outputs = inputs:
+    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = import inputs.systems;
+      imports = [
+        inputs.process-compose-flake.flakeModule
+      ];
+      perSystem = { self', pkgs, lib, ... }: {
+        # `process-compose.foo` will add a flake package output called "foo".
+        # Therefore, this will add a default package that you can build using
+        # `nix build` and run using `nix run`.
+        process-compose."default" = { ... }:
+          {
+            imports = [
+              inputs.services-flake.processComposeModules.default
+            ];
+
+            services.cargo-doc-live."cargo-doc-live1" = {
+              src = inputs.self;
+              enable = true;
+              port = 8009;
+            };
+
+            settings.processes.test = {
+              command = pkgs.writeShellApplication {
+                name = "cargo-doc-live-test";
+                runtimeInputs = [ pkgs.curl ];
+                text = ''
+                  curl http://127.0.0.1:8009/test
+                '';
+              };
+              depends_on."cargo-doc-live1".condition = "process_healthy";
+            };
+          };
+      };
+    };
+}

example/cargo-doc-live/src/main.rs

@@ -0,0 +1,3 @@
+fn main() {
+    println!("Hello, world!");
+}

nix/cargo-doc-live.nix

@@ -0,0 +1,83 @@
+{ pkgs, lib, name, config, ... }:
+let
+  inherit (lib) types;
+in
+{
+  options = {
+    enable = lib.mkEnableOption name;
+
+    src = lib.mkOption {
+      type = types.path;
+      description = "The src of the cargo";
+    };
+
+    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 "${config.src}/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 =
+          {
+            "${name}-cargo-doc" = {
+              command = pkgs.writeShellApplication {
+                name = "cargo-doc";
+                runtimeInputs = with pkgs; [ cargo cargo-watch nodePackages.browser-sync ];
+                text =
+                  let
+                    browser-sync = lib.getExe pkgs.nodePackages.browser-sync;
+                    cargo-watch = lib.getExe pkgs.cargo-watch;
+                    cargo = lib.getExe pkgs.cargo;
+                  in
+                  ''
+                    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 = pkgs.writeShellApplication {
+                name = "browser-sync";
+                runtimeInputs = with pkgs; [ nodePackages.browser-sync ];
+                text =
+                  ''
+                    ${lib.getExe pkgs.nodePackages.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/default.nix

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