From 233b063b08b6a82921d26fb5a86e15c2b94a72ee Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Tue, 21 Mar 2023 14:37:09 +0100
Subject: [PATCH] Move store docs to 'nix help-stores'

Why not 'nix help stores'? Well, 'nix help <arg>' already means 'show
help on the "arg" subcommand'.
---
 src/libstore/globals.hh |  5 ++++-
 src/nix/help-stores.md  |  7 +++++++
 src/nix/main.cc         | 32 +++++++++++++++++++++++++++++++-
 src/nix/nix.md          |  5 ++---
 src/nix/store.cc        |  7 -------
 src/nix/store.md        |  9 ---------
 6 files changed, 44 insertions(+), 21 deletions(-)
 create mode 100644 src/nix/help-stores.md
 delete mode 100644 src/nix/store.md

diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh
index 93086eaf8..4382d1b85 100644
--- a/src/libstore/globals.hh
+++ b/src/libstore/globals.hh
@@ -97,7 +97,10 @@ public:
     Path nixDaemonSocketFile;
 
     Setting<std::string> storeUri{this, getEnv("NIX_REMOTE").value_or("auto"), "store",
-        "The default Nix store to use."};
+        R"(
+          The URL of the Nix store to use. See [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md)
+          for supported store types and settings.
+        )"};
 
     Setting<bool> keepFailed{this, false, "keep-failed",
         "Whether to keep temporary directories of failed builds."};
diff --git a/src/nix/help-stores.md b/src/nix/help-stores.md
new file mode 100644
index 000000000..a33a7ea70
--- /dev/null
+++ b/src/nix/help-stores.md
@@ -0,0 +1,7 @@
+R"(
+
+Nix supports different types of stores. These are described below.
+
+@stores@
+
+)"
diff --git a/src/nix/main.cc b/src/nix/main.cc
index 6caca9c22..5981028f7 100644
--- a/src/nix/main.cc
+++ b/src/nix/main.cc
@@ -223,6 +223,14 @@ static void showHelp(std::vector<std::string> subcommand, NixArgs & toplevel)
     std::cout << renderMarkdownToTerminal(markdown) << "\n";
 }
 
+static NixArgs & getNixArgs(Command & cmd)
+{
+    assert(cmd.parent);
+    MultiCommand * toplevel = cmd.parent;
+    while (toplevel->parent) toplevel = toplevel->parent;
+    return dynamic_cast<NixArgs &>(*toplevel);
+}
+
 struct CmdHelp : Command
 {
     std::vector<std::string> subcommand;
@@ -252,12 +260,34 @@ struct CmdHelp : Command
         assert(parent);
         MultiCommand * toplevel = parent;
         while (toplevel->parent) toplevel = toplevel->parent;
-        showHelp(subcommand, dynamic_cast<NixArgs &>(*toplevel));
+        showHelp(subcommand, getNixArgs(*this));
     }
 };
 
 static auto rCmdHelp = registerCommand<CmdHelp>("help");
 
+struct CmdHelpStores : Command
+{
+    std::string description() override
+    {
+        return "show help about store types and their settings";
+    }
+
+    std::string doc() override
+    {
+        return
+          #include "help-stores.md"
+          ;
+    }
+
+    void run() override
+    {
+        showHelp({"help-stores"}, getNixArgs(*this));
+    }
+};
+
+static auto rCmdHelpStores = registerCommand<CmdHelpStores>("help-stores");
+
 void mainWrapped(int argc, char * * argv)
 {
     savedArgv = argv;
diff --git a/src/nix/nix.md b/src/nix/nix.md
index 0a90fa6c9..e1865b31c 100644
--- a/src/nix/nix.md
+++ b/src/nix/nix.md
@@ -220,8 +220,7 @@ operate are determined as follows:
 
 # Nix stores
 
-Most `nix` subcommands operate on a *Nix store*.
-
-TODO: list store types, options
+Most `nix` subcommands operate on a *Nix store*. These are documented
+in [`nix help-stores`](./nix3-help-stores.md).
 
 )""
diff --git a/src/nix/store.cc b/src/nix/store.cc
index 72b037488..2879e03b3 100644
--- a/src/nix/store.cc
+++ b/src/nix/store.cc
@@ -12,13 +12,6 @@ struct CmdStore : virtual NixMultiCommand
         return "manipulate a Nix store";
     }
 
-    std::string doc() override
-    {
-        return
-          #include "store.md"
-          ;
-    }
-
     Category category() override { return catUtility; }
 
     void run() override
diff --git a/src/nix/store.md b/src/nix/store.md
deleted file mode 100644
index d80a3b1be..000000000
--- a/src/nix/store.md
+++ /dev/null
@@ -1,9 +0,0 @@
-R"(
-
-# Store types
-
-Nix supports different types of stores. These are listed below.
-
-@stores@
-
-)"