Merge pull request #7379 from fricklerhandwerk/refactor-generate-options

refactor rendering documentation of options

doc/manual/generate-options.nix

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

doc/manual/local.mk

@@ -29,19 +29,19 @@ nix-eval = $(dummy-env) $(bindir)/nix eval --experimental-features nix-command -
 $(d)/%.1: $(d)/src/command-ref/%.md
 	@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=1 $^.tmp -o $@
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
 	@rm $^.tmp
 
 $(d)/%.8: $(d)/src/command-ref/%.md
 	@printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=8 $^.tmp -o $@
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@
 	@rm $^.tmp
 
 $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
 	@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=5 $^.tmp -o $@
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
 	@rm $^.tmp
 
 $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli

doc/manual/src/command-ref/nix-build.md

@@ -53,16 +53,18 @@ All options not listed here are passed to `nix-store
 --realise`, except for `--arg` and `--attr` / `-A` which are passed to
 `nix-instantiate`.
 
-  - [`--no-out-link`]{#opt-no-out-link}\
+  - <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
+
     Do not create a symlink to the output path. Note that as a result
     the output does not become a root of the garbage collector, and so
-    might be deleted by `nix-store
+    might be deleted by `nix-store --gc`.
-                    --gc`.
+
+  - <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
 
-  - [`--dry-run`]{#opt-dry-run}\
     Show what store paths would be built or downloaded.
 
-  - [`--out-link`]{#opt-out-link} / `-o` *outlink*\
+  - <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-o` *outlink*
+
     Change the name of the symlink to the output path created from
     `result` to *outlink*.
 

doc/manual/src/command-ref/nix-store.md

@@ -22,7 +22,8 @@ This section lists the options that are common to all operations. These
 options are allowed for every subcommand, though they may not always
 have an effect.
 
-  - [`--add-root`]{#opt-add-root} *path*\
+  - <span id="opt-add-root">[`--add-root`](#opt-add-root)</span> *path*
+
     Causes the result of a realisation (`--realise` and
     `--force-realise`) to be registered as a root of the garbage
     collector. *path* will be created as a symlink to the resulting