Document each store type on its own page

This makes for more useful manual table of contents, that displays the information at a glance. The `nix help-stores` command is kept as-is, even though it will show up in the manual with the same information as these pages due to the way it is written as a "`--help`-style" command. Deciding what to do with that command is left for a later PR.
NixLayeredStore · Nov 30, 2023 · 98d2db0 · 98d2db0
1 parent 44d21f6
commit 98d2db0
Show file tree

Hide file tree

Showing 18 changed files with 84 additions and 51 deletions.
diff --git a/.gitignore b/.gitignore
@@ -22,6 +22,7 @@ perl/Makefile.config
 /doc/manual/xp-features.json
 /doc/manual/src/SUMMARY.md
 /doc/manual/src/SUMMARY-rl-next.md
+/doc/manual/src/store-types
 /doc/manual/src/command-ref/new-cli
 /doc/manual/src/command-ref/conf-file.md
 /doc/manual/src/command-ref/experimental-features-shortlist.md

diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
@@ -3,7 +3,7 @@ let
     attrNames attrValues fromJSON listToAttrs mapAttrs groupBy
     concatStringsSep concatMap length lessThan replaceStrings sort;
   inherit (import <nix/utils.nix>) attrsToList concatStrings optionalString filterAttrs trim squash unique;
-  showStoreDocs = import ./generate-store-info.nix;
+  showStoreDocs = import <nix/generate-store-info.nix>;
 in
 
 inlineHTML: commandDump:
@@ -75,7 +75,18 @@ let
       # 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 inlineHTML commandInfo.stores) ] details.doc);
+        (replaceStrings
+          [ "@stores@" ]
+          [
+            (let
+               storePages = builtins.removeAttrs (showStoreDocs {
+                 inherit inlineHTML;
+                 inherit (commandInfo) stores;
+                 headingLevel = "##";
+               }) [ "SUMMARY.md" ];
+             in concatStrings (attrValues storePages))
+          ]
+          details.doc);
 
       maybeOptions = let
         allVisibleOptions = filterAttrs

diff --git a/doc/manual/generate-settings.nix b/doc/manual/generate-settings.nix
@@ -1,6 +1,6 @@
 let
   inherit (builtins) attrValues concatStringsSep isAttrs isBool mapAttrs;
-  inherit (import ./utils.nix) concatStrings indent optionalString squash;
+  inherit (import <nix/utils.nix>) concatStrings indent optionalString squash;
 in
 
 # `inlineHTML` is a hack to accommodate inconsistent output from `lowdown`

diff --git a/doc/manual/generate-store-info.nix b/doc/manual/generate-store-info.nix
@@ -1,45 +1,54 @@
 let
-  inherit (builtins) attrValues mapAttrs;
-  inherit (import ./utils.nix) concatStrings optionalString;
-  showSettings = import ./generate-settings.nix;
+  inherit (builtins) attrNames listToAttrs concatStringsSep;
+  inherit (import <nix/utils.nix>) optionalString filterAttrs trim squash unique;
+  showSettings = import <nix/generate-settings.nix>;
 in
 
-inlineHTML: storesInfo:
+{ inlineHTML, stores, headingLevel ? "#" }:
 
 let
 
-  showStore = name: { settings, doc, experimentalFeature }:
+  showStore = { name, slug }: { settings, doc, experimentalFeature }:
     let
-
-    result = ''
-      ## ${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 ''
+      ${headingLevel} ${name}
 
       ${doc}
 
       ${experimentalFeatureNote}
 
-      ### Settings
+      ${headingLevel}# Settings
 
       ${showSettings { prefix = "store-${slug}"; inherit inlineHTML; } settings}
     '';
 
+  storesList = map
+    (name: rec {
+      inherit name;
       # markdown doesn't like spaces in URLs
       slug = builtins.replaceStrings [ " " ] [ "-" ] name;
+      filename = "${slug}.md";
+      page = showStore { inherit name slug; } stores.${name};
+    })
+    (attrNames stores);
 
-    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;
+  tableOfContents = let
+    showEntry = store:
+      "    - [${store.name}](store-types/${store.filename})";
+    in concatStringsSep "\n" (map showEntry storesList) + "\n";
 
-in concatStrings (attrValues (mapAttrs showStore storesInfo))
+in listToAttrs (map (s: { name = s.filename; value = s.page; }) storesList) // { "SUMMARY.md" = tableOfContents; }
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
@@ -97,10 +97,15 @@ $(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
 	$(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/SUMMARY-rl-next.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
+$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/store-types $(d)/src/SUMMARY-rl-next.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
 	@cp $< $@
 	@$(call process-includes,$@,$@)
 
+$(d)/src/store-types: $(d)/nix.json $(d)/utils.nix $(d)/generate-store-info.nix $(doc_nix)
+	@rm -rf $@ $@.tmp
+	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-store-info.nix { inlineHTML = true; inherit (builtins.fromJSON (builtins.readFile $<)) stores; }'
+	@mv $@.tmp $@
+
 $(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 $(doc_nix)
 	@rm -rf $@ $@.tmp
 	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)'
@@ -200,7 +205,7 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
 # `@docroot@` is to be preserved for documenting the mechanism
 # FIXME: maybe contributing guides should live right next to the code
 # instead of in the manual
-$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next.md
+$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store-types $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next.md
 	$(trace-gen) \
 		tmp="$$(mktemp -d)"; \
 		cp -r doc/manual "$$tmp"; \

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
@@ -20,6 +20,8 @@
   - [File System Object](store/file-system-object.md)
   - [Store Object](store/store-object.md)
   - [Store Path](store/store-path.md)
+  - [Store Types](store-types.md)
+  {{#include ./store-types/SUMMARY.md}}
 - [Nix Language](language/index.md)
   - [Data Types](language/values.md)
   - [Language Constructs](language/constructs.md)

diff --git a/doc/manual/src/contributing/cli-guideline.md b/doc/manual/src/contributing/cli-guideline.md
@@ -426,7 +426,7 @@ This leads to the following guidelines:
 ### Examples
 
 
-This is bad, because all keys must be assumed to be store implementations:
+This is bad, because all keys must be assumed to be store types:
 
 ```json
 {

diff --git a/doc/manual/src/release-notes/rl-2.15.md b/doc/manual/src/release-notes/rl-2.15.md
@@ -30,7 +30,7 @@
 
 * 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).
+* Nix stores and their settings are now documented in [`nix help-stores`].
 
 * Documentation for operations of `nix-store` and `nix-env` are now available on separate pages of the manual.
   They include all common options that can be specified and common environment variables that affect these commands.

diff --git a/doc/manual/src/store/types/index.md.in → doc/manual/src/store/types/index.md b/doc/manual/src/store/types/index.md.in → doc/manual/src/store/types/index.md
@@ -38,5 +38,3 @@ store as follows:
   does not exist.
 
 * Otherwise, use the [local store](#local-store) `/nix/store`.
-
-@stores@
diff --git a/src/libcmd/common-eval-args.cc b/src/libcmd/common-eval-args.cc
@@ -141,7 +141,7 @@ MixEvalArgs::MixEvalArgs()
         .longName = "eval-store",
         .description =
           R"(
-            The [URL of the Nix store](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format)
+            The [URL of the Nix store](@docroot@/store-types.md#store-url-format)
             to use for evaluation, i.e. to store derivations (`.drv` files) and inputs referenced by them.
           )",
         .category = category,

diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc
@@ -4460,7 +4460,7 @@ void EvalState::createBaseEnv()
         .doc = R"(
           Logical file system location of the [Nix store](@docroot@/glossary.md#gloss-store) currently in use.
 
-          This value is determined by the `store` parameter in [Store URLs](@docroot@/command-ref/new-cli/nix3-help-stores.md):
+          This value is determined by the `store` parameter in [Store URLs](@docroot@/store-types.md#store-urls):
 
           ```shell-session
           $ nix-instantiate --store 'dummy://?store=/blah' --eval --expr builtins.storeDir

diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh
@@ -117,10 +117,11 @@ public:
 
     Setting<std::string> storeUri{this, getEnv("NIX_REMOTE").value_or("auto"), "store",
         R"(
-          The [URL of the Nix store](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format)
+          The [URL of the Nix store](@docroot@/store-types.md#store-url-format)
           to use for most operations.
-          See [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md)
-          for supported store types and settings.
+          See the
+          [Store Types](@docroot@/store-types.md)
+          section of the manual for supported store types and settings.
         )"};
 
     Setting<bool> keepFailed{this, false, "keep-failed",
@@ -759,7 +760,7 @@ public:
         Strings{"https://cache.nixos.org/"},
         "substituters",
         R"(
-          A list of [URLs of Nix stores](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format) to be used as substituters, separated by whitespace.
+          A list of [URLs of Nix stores](@docroot@/store-types.md#store-url-format) to be used as substituters, separated by whitespace.
           A substituter is an additional [store]{@docroot@/glossary.md##gloss-store} from which Nix can obtain [store objects](@docroot@/glossary.md#gloss-store-object) instead of building them.
 
           Substituters are tried based on their priority value, which each substituter can set independently.
@@ -778,7 +779,7 @@ public:
     Setting<StringSet> trustedSubstituters{
         this, {}, "trusted-substituters",
         R"(
-          A list of [Nix store URLs](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format), separated by whitespace.
+          A list of [Nix store URLs](@docroot@/store-types.md#store-url-format), separated by whitespace.
           These are not used by default, but users of the Nix daemon can enable them by specifying [`substituters`](#conf-substituters).
 
           Unprivileged users (those set in only [`allowed-users`](#conf-allowed-users) but not [`trusted-users`](#conf-trusted-users)) can pass as `substituters` only those URLs listed in `trusted-substituters`.

diff --git a/src/libstore/remote-store.cc b/src/libstore/remote-store.cc
@@ -20,7 +20,7 @@
 
 namespace nix {
 
-/* TODO: Separate these store impls into different files, give them better names */
+/* TODO: Separate these store types into different files, give them better names */
 RemoteStore::RemoteStore(const Params & params)
     : RemoteStoreConfig(params)
     , Store(params)

diff --git a/src/libstore/ssh-store-config.hh b/src/libstore/ssh-store-config.hh
@@ -20,7 +20,7 @@ struct CommonSSHStoreConfig : virtual StoreConfig
 
     const Setting<std::string> remoteStore{this, "", "remote-store",
         R"(
-          [Store URL](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format)
+          [Store URL](@docroot@/store-types.md#store-url-format)
           to be used on the remote machine. The default is `auto`
           (i.e. use the Nix daemon or `/nix/store` directly).
         )"};

diff --git a/src/libstore/store-api.hh b/src/libstore/store-api.hh
@@ -30,7 +30,7 @@
 namespace nix {
 
 /**
- * About the class hierarchy of the store implementations:
+ * About the class hierarchy of the store types:
  *
  * Each store type `Foo` consists of two classes:
  *
@@ -962,7 +962,7 @@ OutputPathMap resolveDerivedPath(Store &, const DerivedPath::Built &, Store * ev
  * - ‘ssh://[user@]<host>’: A remote Nix store accessed by running
  *   ‘nix-store --serve’ via SSH.
  *
- * You can pass parameters to the store implementation by appending
+ * You can pass parameters to the store type by appending
  * ‘?key=value&key=value&...’ to the URI.
  */
 ref<Store> openStore(const std::string & uri = settings.storeUri.get(),

diff --git a/src/libutil/experimental-features.cc b/src/libutil/experimental-features.cc
@@ -252,7 +252,7 @@ constexpr std::array<ExperimentalFeatureDetails, numXpFeatures> xpFeatureDetails
         .tag = Xp::ReadOnlyLocalStore,
         .name = "read-only-local-store",
         .description = R"(
-            Allow the use of the `read-only` parameter in [local store](@docroot@/command-ref/new-cli/nix3-help-stores.md#local-store) URIs.
+            Allow the use of the `read-only` parameter in [local store](@docroot@/store-types/Local-Store.md) URIs.
         )",
     },
     {

diff --git a/src/nix/local.mk b/src/nix/local.mk
@@ -43,11 +43,13 @@ src/nix/generated-doc/files/%.md: doc/manual/src/command-ref/files/%.md
 
 src/nix/profile.cc: src/nix/profile.md src/nix/generated-doc/files/profiles.md.gen.hh
 
-src/nix/generated-doc/help-stores.md: doc/manual/src/store/types/index.md.in
+src/nix/generated-doc/help-stores.md: doc/manual/src/store/types/index.md
 	@mkdir -p $$(dirname $@)
 	@echo 'R"(' >> $@.tmp
-	@echo >> $@.tmp
+	@echo '' >> $@.tmp
 	@cat $^ >> $@.tmp
-	@echo >> $@.tmp
+	@echo '' >> $@.tmp
+	@echo '@stores@' >> $@.tmp
+	@echo '' >> $@.tmp
 	@echo ')"' >> $@.tmp
 	@mv $@.tmp $@
diff --git a/src/nix/nix.md b/src/nix/nix.md
@@ -235,8 +235,12 @@ operate are determined as follows:
 
 # Nix stores
 
-Most `nix` subcommands operate on a *Nix store*. These are documented
-in [`nix help-stores`](./nix3-help-stores.md).
+Most `nix` subcommands operate on a *Nix store*.
+The various store types are documented in the
+[Store Types](@docroot@/store-types.md)
+section of the manual.
+
+The same information is also available from the [`nix help-stores`](./nix3-help-stores.md) command.
 
 # Shebang interpreter
-Original file line number
+Diff line change
@@ Expand Up / @@ -426,7 +426,7 @@ This leads to the following guidelines: @@
     ### Examples
-    This is bad, because all keys must be assumed to be store implementations:
+    This is bad, because all keys must be assumed to be store types:
     ```json
     {
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
Expand Up		@@ -38,5 +38,3 @@ store as follows:
		does not exist.

		* Otherwise, use the [local store](#local-store) `/nix/store`.

		@stores@