doc: init server; nix run .#docs (#1328)

Adds:

- `serve-docs` to the default devShell
- `packages.serve-docs`
- `apps.docs`

Having `apps.docs` defined causes `nix run .#docs` to run the "app"
instead of `packages.docs`. `nix build .#docs` will still build the
"package", not the "app".

The `serve-docs` script added to the devShell runs `nix run .#docs`
instead of having `packages.serve-docs` in its closure. This avoids the
devShell actually building the docs.

Added a note to `doc/src/modules.md`.

Link: https://github.com/nix-community/stylix/pull/1328

Reviewed-by: awwpotato <awwpotato@voidq.com>
Co-authored-by: NAHO <90870942+trueNAHO@users.noreply.github.com>
Reviewed-by: NAHO <90870942+trueNAHO@users.noreply.github.com>

doc/server.nix

@@ -0,0 +1,22 @@
+{
+  docs,
+  http-server,
+  writeShellApplication,
+}:
+writeShellApplication {
+  name = "serve-docs";
+  runtimeInputs = [ http-server ];
+  runtimeEnv.server_flags = [
+    # Search for available port
+    "--port=0"
+
+    # Disable browser cache
+    "-c-1"
+
+    # Open using xdg-open
+    "-o"
+  ];
+  text = ''
+    http-server ${docs} "''${server_flags[@]}"
+  '';
+}

doc/src/modules.md

@@ -247,6 +247,9 @@ syntax for formatting and links.
 For modules needing more general documentation, add a `description` to
 `modules/«module»/meta.nix`:
 
+You can build and view the documentation by running `nix run .#docs`, or
+`serve-docs` from within the dev shell.
+
 ```markdown
 # Module Name
 

flake/dev-shell.nix

@@ -25,6 +25,18 @@
             "$@"
         '';
       };
+
+      # The shell should not directly depend on `packages.serve-docs`, because
+      # that'd build the docs before entering the shell. Instead, we want to
+      # build the docs only when running 'serve-docs'.
+      #
+      # For a similar reason, we can't use `self` as a reference to the flake:
+      # `self` represents the flake as it was when the devshell was evaluated,
+      # not the local flake worktree that has possibly been modified since
+      # entering the devshell.
+      build-and-run-docs = pkgs.writeShellScriptBin "serve-docs" ''
+        nix run .#docs
+      '';
     in
     {
       devShells = {
@@ -35,6 +47,7 @@
           packages =
             [
               stylix-check
+              build-and-run-docs
               inputs'.home-manager.packages.default
               config.formatter
             ]

flake/packages.nix

@@ -8,6 +8,9 @@
       # are derivations.
       checks = config.packages;
 
+      # Make 'nix run .#docs' serve the docs
+      apps.docs.program = config.packages.serve-docs;
+
       packages = lib.mkMerge [
         # Testbeds are virtual machines based on NixOS, therefore they are
         # only available for Linux systems.
@@ -22,6 +25,9 @@
             inherit (inputs.nixpkgs.lib) nixosSystem;
             inherit (inputs.home-manager.lib) homeManagerConfiguration;
           };
+          serve-docs = pkgs.callPackage ../doc/server.nix {
+            inherit (config.packages) docs;
+          };
           palette-generator = pkgs.callPackage ../palette-generator { };
         }
       ];