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,44 @@
+# cargo-doc-live
+
+[cargo-doc-live] is live server version of `cargo doc` ― edit Rust code, and see the docs view in your web browser update automatically.
+
+https://github.com/srid/cargo-doc-live/assets/3998/37378858-dda1-40fb-8f6a-f76dc857a661
+
+{#start}
+
+## Getting started
+
+```nix
+# In `perSystem.process-compose.<name>`
+{
+  services.cargo-doc-live."cargo-doc-live1".enable = true;
+}
+```
+
+{#port}
+
+### The port for `cargo doc`, the default value is 8008, while you could override it if 8008 is in use for another service.
+
+```nix
+{
+  services.cargo-doc-live."cargo-doc-live1" = {
+    enable = true;
+    projectRoot = ./.;
+    port = 8080;
+  };
+}
+```
+
+{#crateName}
+
+### The crate to use when opening docs in browser, the crate name will be derived from Cargo.toml.
+
+```nix
+{
+  services.cargo-doc-live."cargo-doc-live1" = {
+    enable = true;
+    projectRoot = ./.;
+    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/README.md

@@ -0,0 +1,8 @@
+A demonstration of cargo-doc-live.
+
+To run,
+
+```
+cd ./example/cargo-doc-live
+nix run .#cargo-doc-live
+```

example/cargo-doc-live/flake.nix

@@ -0,0 +1,54 @@
+{
+  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."cargo-doc-live" = _:
+          {
+            tui = false;
+
+            imports = [
+              inputs.services-flake.processComposeModules.default
+            ];
+
+            preHook = ''
+              # Set pipefail option for safer bash
+              set -euo pipefail
+
+              # Copy project root to a mutable area
+              export HOME="$TMP"
+              cp -r ${inputs.self} "$HOME"/project
+              chmod -R a+w "$HOME"/project
+              cd "$HOME"/project
+            '';
+
+            services.cargo-doc-live."cargo-doc-live1" = {
+              projectRoot = 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-browser-sync".condition = "process_healthy";
+            };
+          };
+      };
+    };
+}

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

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

flake.nix

@@ -28,6 +28,10 @@
         };
         dir = "./example/share-services/pgweb";
       };
+      cargo-doc-live-example = {
+        inherit overrideInputs;
+        dir = "./example/cargo-doc-live";
+      };
       test = {
         inherit overrideInputs;
         dir = "./test";

nix/cargo-doc-live.nix

@@ -0,0 +1,91 @@
+{ pkgs, lib, name, config, ... }:
+let
+  inherit (lib) types;
+in
+{
+  options = {
+    enable = lib.mkEnableOption name;
+
+    projectRoot = lib.mkOption {
+      type = types.path;
+      description = "Path to the cargo project root";
+      default = ./.;
+    };
+
+    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.projectRoot}/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 =
+                ''
+                  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 = [ pkgs.nodePackages.browser-sync ];
+              text =
+                ''
+                  browser-sync start --port ${toString config.port} --ss target/doc -s target/doc \
+                  --startPath /${config.crateName}/
+                '';
+            };
+            readiness_probe = {
+              http_get = {
+                scheme = "http";
+                host = "localhost";
+                port = config.port;
+                path = config.crateName;
+              };
+              initial_delay_seconds = 15;
+              period_seconds = 10;
+              timeout_seconds = 2;
+              success_threshold = 1;
+              failure_threshold = 5;
+            };
+            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
   ];
 }