Merge pull request #332466 from hsjobeki/doc/compressDrv

Doc: pkgs{compressDrv,compressDrvWeb} improve clarity

pkgs/build-support/compress-drv/default.nix

@@ -4,15 +4,16 @@
   runCommand,
 }:
 /**
-  #  compressDrv compresses files in a given derivation.
+  Compresses files of a given derivation, and returns a new derivation with
+  compressed files
 
-  ## Inputs:
+  # Inputs
 
   `formats` ([String])
 
   : List of file extensions to compress. Example: `["txt" "svg" "xml"]`.
 
-  `compressors` (String -> String)
+  `compressors` ( { ${fileExtension} :: String })
 
   : Map a desired extension (e.g. `gz`) to a compress program.
 
@@ -21,19 +22,33 @@
     target filename.
 
     Compressor must:
+
     - read symlinks (thus --force is needed to gzip, zstd, xz).
     - keep the original file in place (--keep).
 
-  Example:
+  # Type
 
   ```
-  {
-    xz = "${xz}/bin/xz --force --keep {}";
+  compressDrv :: Derivation -> { formats :: [ String ]; compressors :: { ${fileExtension} :: String; } } -> Derivation
+  ```
+
+  # Examples
+  :::{.example}
+  ## `pkgs.compressDrv` usage example
+  ```
+  compressDrv pkgs.spdx-license-list-data.json {
+    formats = ["json"];
+    compressors = {
+      "json" = "${zopfli}/bin/zopfli --keep {}";
+    };
   }
+  =>
+  «derivation /nix/store/...-spdx-license-list-data-3.24.0-compressed.drv»
   ```
 
-  See compressDrvWeb, which is a wrapper on top of compressDrv, for broader use
+  See also pkgs.compressDrvWeb, which is a wrapper on top of compressDrv, for broader usage
   examples.
+  :::
 */
 drv:
 { formats, compressors, ... }:

pkgs/build-support/compress-drv/web.nix

@@ -4,10 +4,39 @@
   compressDrv,
 }:
 /**
-  # compressDrvWeb compresses a derivation for common web server use.
+  compressDrvWeb compresses a derivation for common web server use.
 
   Useful when one wants to pre-compress certain static assets and pass them to
-  the web server. For example, `pkgs.gamja` creates this derivation:
+  the web server.
+
+  # Inputs
+
+  `formats` ([String])
+
+  : List of file extensions to compress.
+
+    Defaults to common formats that compress well.
+
+  `extraFormats` ([ String ])
+
+  : Extra extensions to compress in addition to `formats`.
+
+  `compressors` ( { ${fileExtension} :: String })
+
+  : Map a desired extension (e.g. `gz`) to a compress program.
+
+  # Type
+
+  ```
+  compressDrvWeb :: Derivation -> { formats :: [ String ]; extraFormats :: [ String ]; compressors :: { ${fileExtension} :: String; } } -> Derivation
+  ```
+
+  # Examples
+  :::{.example}
+  ## `pkgs.compressDrvWeb` full usage example with `pkgs.gamja` and a webserver
+  ```nix
+
+  For example, building `pkgs.gamja` produces the following output:
 
     /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/
     ├── index.2fd01148.js
@@ -17,8 +46,15 @@
     ├── index.html
     └── manifest.webmanifest
 
-  `pkgs.compressDrvWeb pkgs.gamja`:
+  With `pkgs.compressDrvWeb`, one can compress these files:
 
+  ```nix
+  pkgs.compressDrvWeb pkgs.gamja {}
+  =>
+  «derivation /nix/store/...-gamja-compressed.drv»
+  ```
+
+  ```bash
   /nix/store/f5ryid7zrw2hid7h9kil5g5j29q5r2f7-gamja-1.0.0-beta.9-compressed
   ├── index.2fd01148.js -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.2fd01148.js
   ├── index.2fd01148.js.br
@@ -38,42 +74,35 @@
   ├── manifest.webmanifest -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/manifest.webmanifest
   ├── manifest.webmanifest.br
   └── manifest.webmanifest.gz
+  ```
 
-  When this `-compressed` directory is passed to a properly configured web
-  server, it will serve those pre-compressed files:
+  When the `-compressed` derivation is passed to a properly configured web server,
+  it enables direct serving of the pre-compressed files.
 
+  ```shell-session
   $ curl -I -H 'Accept-Encoding: br' https://irc.example.org/
   <...>
   content-encoding: br
   <...>
+  ```
 
   For example, a caddy configuration snippet for gamja to serve
   the static assets (JS, CSS files) pre-compressed:
 
+  ```nix
+  {
     virtualHosts."irc.example.org".extraConfig = ''
       root * ${pkgs.compressDrvWeb pkgs.gamja {}}
       file_server browse {
           precompressed br gzip
       }
     '';
+  }
+  ```
 
   This feature is also available in nginx via `ngx_brotli` and
   `ngx_http_gzip_static_module`.
-
-  ## Inputs
-
-  `formats` ([String])
-
-  : List of file extensions to compress. Default is common formats that compress
-  well. The list may be expanded.
-
-  `extraFormats` ([String])
-
-  : Extra extensions to compress in addition to `formats`.
-
-  `compressors` (String -> String)
-
-  : See parameter `compressors` of compressDrv.
+  :::
 */
 drv:
 {