diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index 41725aed6..425eea002 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -2,7 +2,8 @@ let
inherit (builtins)
attrNames attrValues fromJSON listToAttrs mapAttrs groupBy
concatStringsSep concatMap length lessThan replaceStrings sort;
- inherit (import ./utils.nix) attrsToList concatStrings optionalString filterAttrs trim squash unique showSettings;
+ inherit (import ./utils.nix) attrsToList concatStrings optionalString filterAttrs trim squash unique;
+ showStoreDocs = import ./generate-store-info.nix;
in
commandDump:
@@ -30,7 +31,7 @@ let
${maybeSubcommands}
- ${maybeDocumentation}
+ ${maybeStoreDocs}
${maybeOptions}
'';
@@ -40,15 +41,15 @@ let
showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "...";
arguments = concatStringsSep " " (map showArgument args);
in ''
- `${command}` [*option*...] ${arguments}
+ `${command}` [*option*...] ${arguments}
'';
maybeSubcommands = optionalString (details ? commands && details.commands != {})
- ''
- where *subcommand* is one of the following:
+ ''
+ where *subcommand* is one of the following:
- ${subcommands}
- '';
+ ${subcommands}
+ '';
subcommands = if length categories > 1
then listCategories
@@ -70,10 +71,11 @@ let
* [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
'';
- # TODO: move this confusing special case out of here when implementing #8496
- maybeDocumentation = optionalString
- (details ? doc)
- (replaceStrings ["@stores@"] [storeDocs] details.doc);
+ # FIXME: this is a hack.
+ # store parameters should not be part of command documentation to begin
+ # with, but instead be rendered on separate pages.
+ maybeStoreDocs = optionalString (details ? doc)
+ (replaceStrings [ "@stores@" ] [ (showStoreDocs commandInfo.stores) ] details.doc);
maybeOptions = let
allVisibleOptions = filterAttrs
@@ -147,35 +149,4 @@ let
" - [${page.command}](command-ref/new-cli/${page.name})";
in concatStringsSep "\n" (map showEntry manpages) + "\n";
- storeDocs =
- let
- showStore = name: { settings, doc, experimentalFeature }:
- let
- experimentalFeatureNote = optionalString (experimentalFeature != null) ''
- > **Warning**
- > This store is part of an
- > [experimental feature](@docroot@/contributing/experimental-features.md).
-
- To use this store, you need to make sure the corresponding experimental feature,
- [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}),
- is enabled.
- For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
-
- ```
- extra-experimental-features = ${experimentalFeature}
- ```
- '';
- in ''
- ## ${name}
-
- ${doc}
-
- ${experimentalFeatureNote}
-
- **Settings**:
-
- ${showSettings { useAnchors = false; } settings}
- '';
- in concatStrings (attrValues (mapAttrs showStore commandInfo.stores));
-
in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }
diff --git a/doc/manual/generate-settings.nix b/doc/manual/generate-settings.nix
new file mode 100644
index 000000000..450771f73
--- /dev/null
+++ b/doc/manual/generate-settings.nix
@@ -0,0 +1,63 @@
+let
+ inherit (builtins) attrValues concatStringsSep isAttrs isBool mapAttrs;
+ inherit (import ./utils.nix) concatStrings indent optionalString squash;
+in
+
+prefix: settingsInfo:
+
+let
+
+ showSetting = prefix: setting: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
+ let
+ result = squash ''
+ - [`${setting}`](#${prefix}-${setting})
+
+ ${indent " " body}
+ '';
+
+ # separate body to cleanly handle indentation
+ body = ''
+ ${description}
+
+ ${experimentalFeatureNote}
+
+ **Default:** ${showDefault documentDefault defaultValue}
+
+ ${showAliases aliases}
+ '';
+
+ experimentalFeatureNote = optionalString (experimentalFeature != null) ''
+ > **Warning**
+ > This setting is part of an
+ > [experimental feature](@docroot@/contributing/experimental-features.md).
+
+ To change this setting, you need to make sure the corresponding experimental feature,
+ [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}),
+ is enabled.
+ For example, include the following in [`nix.conf`](#):
+
+ ```
+ extra-experimental-features = ${experimentalFeature}
+ ${setting} = ...
+ ```
+ '';
+
+ 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:
+ optionalString (aliases != [])
+ "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
+
+ in result;
+
+in concatStrings (attrValues (mapAttrs (showSetting prefix) settingsInfo))
diff --git a/doc/manual/generate-store-info.nix b/doc/manual/generate-store-info.nix
new file mode 100644
index 000000000..7bb2ebad3
--- /dev/null
+++ b/doc/manual/generate-store-info.nix
@@ -0,0 +1,45 @@
+let
+ inherit (builtins) attrValues mapAttrs;
+ inherit (import ./utils.nix) concatStrings optionalString;
+ showSettings = import ./generate-settings.nix;
+in
+
+storesInfo:
+
+let
+
+ showStore = name: { settings, doc, experimentalFeature }:
+ let
+
+ result = ''
+ ## ${name}
+
+ ${doc}
+
+ ${experimentalFeatureNote}
+
+ ### Settings
+
+ ${showSettings "store-${slug}" settings}
+ '';
+
+ # markdown doesn't like spaces in URLs
+ slug = builtins.replaceStrings [ " " ] [ "-" ] name;
+
+ experimentalFeatureNote = optionalString (experimentalFeature != null) ''
+ > **Warning**
+ > This store is part of an
+ > [experimental feature](@docroot@/contributing/experimental-features.md).
+
+ To use this store, you need to make sure the corresponding experimental feature,
+ [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}),
+ is enabled.
+ For example, include the following in [`nix.conf`](#):
+
+ ```
+ extra-experimental-features = ${experimentalFeature}
+ ```
+ '';
+ in result;
+
+in concatStrings (attrValues (mapAttrs showStore storesInfo))
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index abdfd6a62..927854066 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -96,14 +96,14 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli $(d)/sr
@cp $< $@
@$(call process-includes,$@,$@)
-$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(bindir)/nix
+$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(d)/generate-settings.nix $(d)/generate-store-info.nix $(bindir)/nix
@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)/utils.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features-shortlist.md $(bindir)/nix
+$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/generate-settings.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features-shortlist.md $(bindir)/nix
@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
- $(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { useAnchors = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
+ $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-settings.nix "opt-" (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
@mv $@.tmp $@
$(d)/nix.json: $(bindir)/nix
diff --git a/doc/manual/utils.nix b/doc/manual/utils.nix
index 9043dd8cd..849832b2c 100644
--- a/doc/manual/utils.nix
+++ b/doc/manual/utils.nix
@@ -44,63 +44,6 @@ rec {
optionalString = cond: string: if cond then string else "";
- showSetting = { useAnchors }: name: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
- let
- result = squash ''
- - ${if useAnchors
- then ''[`${name}`](#conf-${name})''
- else ''`${name}`''}
-
- ${indent " " body}
- '';
-
- experimentalFeatureNote = optionalString (experimentalFeature != null) ''
- > **Warning**
- > This setting is part of an
- > [experimental feature](@docroot@/contributing/experimental-features.md).
-
- To change this setting, you need to make sure the corresponding experimental feature,
- [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}),
- is enabled.
- For example, include the following in [`nix.conf`](#):
-
- ```
- extra-experimental-features = ${experimentalFeature}
- ${name} = ...
- ```
- '';
-
- # separate body to cleanly handle indentation
- body = ''
- ${description}
-
- ${experimentalFeatureNote}
-
- **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:
- optionalString (aliases != [])
- "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
-
- in result;
-
indent = prefix: s:
concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
-
- showSettings = args: settingsInfo: concatStrings (attrValues (mapAttrs (showSetting args) settingsInfo));
}