Merge pull request #8084 from edolstra/store-docs

Auto-generate store documentation

doc/manual/generate-manpage.nix

@@ -1,4 +1,4 @@
-{ toplevel }:
+cliDumpStr:
 
 with builtins;
 with import ./utils.nix;
@@ -63,7 +63,10 @@ let
         * [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
       '';
 
-      maybeDocumentation = if details ? doc then details.doc else "";
+      maybeDocumentation =
+        if details ? doc
+        then replaceStrings ["@stores@"] [storeDocs] details.doc
+        else "";
 
       maybeOptions = if details.flags == {} then "" else ''
         # Options
@@ -110,13 +113,13 @@ let
       };
     in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
 
-  parsedToplevel = builtins.fromJSON toplevel;
+  cliDump = builtins.fromJSON cliDumpStr;
 
   manpages = processCommand {
     command = "nix";
-    details = parsedToplevel;
+    details = cliDump.args;
     filename = "nix";
-    toplevel = parsedToplevel;
+    toplevel = cliDump.args;
   };
 
   tableOfContents = let
@@ -124,4 +127,18 @@ let
       "    - [${page.command}](command-ref/new-cli/${page.name})";
     in concatStringsSep "\n" (map showEntry manpages) + "\n";
 
+  storeDocs =
+    let
+      showStore = name: { settings, doc }:
+        ''
+          ## ${name}
+
+          ${doc}
+
+          **Settings**:
+
+          ${showSettings { useAnchors = false; } settings}
+        '';
+    in concatStrings (attrValues (mapAttrs showStore cliDump.stores));
+
 in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }

doc/manual/generate-options.nix

@@ -1,41 +0,0 @@
-let
-  inherit (builtins) attrNames concatStringsSep isAttrs isBool;
-  inherit (import ./utils.nix) concatStrings squash splitLines;
-in
-
-optionsInfo:
-let
-  showOption = name:
-    let
-      inherit (optionsInfo.${name}) description documentDefault defaultValue aliases;
-      result = squash ''
-          - <span id="conf-${name}">[`${name}`](#conf-${name})</span>
-
-          ${indent "  " body}
-        '';
-      # separate body to cleanly handle indentation
-      body = ''
-          ${description}
-
-          **Default:** ${showDefault documentDefault defaultValue}
-
-          ${showAliases aliases}
-        '';
-      showDefault = documentDefault: defaultValue:
-        if documentDefault then
-          # a StringMap value type is specified as a string, but
-          # this shows the value type. The empty stringmap is `null` in
-          # JSON, but that converts to `{ }` here.
-          if defaultValue == "" || defaultValue == [] || isAttrs defaultValue
-            then "*empty*"
-            else if isBool defaultValue then
-              if defaultValue then "`true`" else "`false`"
-            else "`${toString defaultValue}`"
-        else "*machine-specific*";
-      showAliases = aliases:
-          if aliases == [] then "" else
-            "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
-      indent = prefix: s:
-        concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
-      in result;
-in concatStrings (map showOption (attrNames optionsInfo))

doc/manual/local.mk

@@ -60,17 +60,17 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
 	@$(call process-includes,$@,$@)
 
 $(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix
-	@rm -rf $@
-	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix { toplevel = builtins.readFile $<; }'
+	@rm -rf $@ $@.tmp
+	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix (builtins.readFile $<)'
 	@mv $@.tmp $@
 
-$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/generate-options.nix $(d)/src/command-ref/conf-file-prefix.md $(bindir)/nix
+$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/src/command-ref/conf-file-prefix.md $(bindir)/nix
 	@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
-	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-options.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
+	$(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { useAnchors = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
 	@mv $@.tmp $@
 
 $(d)/nix.json: $(bindir)/nix
-	$(trace-gen) $(dummy-env) $(bindir)/nix __dump-args > $@.tmp
+	$(trace-gen) $(dummy-env) $(bindir)/nix __dump-cli > $@.tmp
 	@mv $@.tmp $@
 
 $(d)/conf-file.json: $(bindir)/nix

doc/manual/src/package-management/s3-substituter.md

@@ -1,41 +1,11 @@
 # Serving a Nix store via S3
 
-Nix has built-in support for storing and fetching store paths from
+Nix has [built-in support](@docroot@/command-ref/new-cli/nix3-help-stores.md#s3-binary-cache-store)
+for storing and fetching store paths from
 Amazon S3 and S3-compatible services. This uses the same *binary*
 cache mechanism that Nix usually uses to fetch prebuilt binaries from
 [cache.nixos.org](https://cache.nixos.org/).
 
-The following options can be specified as URL parameters to the S3 URL:
-
-  - `profile`\
-    The name of the AWS configuration profile to use. By default Nix
-    will use the `default` profile.
-
-  - `region`\
-    The region of the S3 bucket. `us–east-1` by default.
-    
-    If your bucket is not in `us–east-1`, you should always explicitly
-    specify the region parameter.
-
-  - `endpoint`\
-    The URL to your S3-compatible service, for when not using Amazon S3.
-    Do not specify this value if you're using Amazon S3.
-    
-    > **Note**
-    > 
-    > This endpoint must support HTTPS and will use path-based
-    > addressing instead of virtual host based addressing.
-
-  - `scheme`\
-    The scheme used for S3 requests, `https` (default) or `http`. This
-    option allows you to disable HTTPS for binary caches which don't
-    support it.
-    
-    > **Note**
-    > 
-    > HTTPS should be used if the cache might contain sensitive
-    > information.
-
 In this example we will use the bucket named `example-nix-cache`.
 
 ## Anonymous Reads to your S3-compatible binary cache

doc/manual/src/release-notes/rl-next.md

@@ -26,4 +26,8 @@
   ```shell-session
   $ nix path-info /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^*
   ```
-  provides information about each of its outputs.
+  provides information about each of its outputs.
+
+* The experimental command `nix describe-stores` has been removed.
+
+* Nix stores and their settings are now documented in [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md).

doc/manual/utils.nix

@@ -38,4 +38,46 @@ rec {
 
   filterAttrs = pred: set:
     listToAttrs (concatMap (name: let v = set.${name}; in if pred name v then [(nameValuePair name v)] else []) (attrNames set));
+
+  showSetting = { useAnchors }: name: { description, documentDefault, defaultValue, aliases, value }:
+    let
+      result = squash ''
+          - ${if useAnchors
+              then ''<span id="conf-${name}">[`${name}`](#conf-${name})</span>''
+              else ''`${name}`''}
+
+          ${indent "  " body}
+        '';
+
+      # separate body to cleanly handle indentation
+      body = ''
+          ${description}
+
+          **Default:** ${showDefault documentDefault defaultValue}
+
+          ${showAliases aliases}
+        '';
+
+      showDefault = documentDefault: defaultValue:
+        if documentDefault then
+          # a StringMap value type is specified as a string, but
+          # this shows the value type. The empty stringmap is `null` in
+          # JSON, but that converts to `{ }` here.
+          if defaultValue == "" || defaultValue == [] || isAttrs defaultValue
+            then "*empty*"
+            else if isBool defaultValue then
+              if defaultValue then "`true`" else "`false`"
+            else "`${toString defaultValue}`"
+        else "*machine-specific*";
+
+      showAliases = aliases:
+          if aliases == [] then "" else
+            "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
+
+      indent = prefix: s:
+        concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
+
+    in result;
+
+  showSettings = args: settingsInfo: concatStrings (attrValues (mapAttrs (showSetting args) settingsInfo));
 }