Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

generate command docs (#65608)

Jeff Bruemmer257f23f104cf
diff --git a/resources/commands/footer.md b/resources/commands/footer.md
new file mode 100644
index 00000000000..b5a80fe2ff7
--- /dev/null
+++ b/resources/commands/footer.md
@@ -0,0 +1,9 @@
+## Additional useful commands
+
+### H2 SQL Shell
+
+Open an SQL shell for the Metabase H2 DB:
+
+```sh
+java -cp metabase.jar org.h2.tools.Shell -url jdbc:h2:/path/to/metabase.db
+```
diff --git a/resources/commands/header.md b/resources/commands/header.md
new file mode 100644
index 00000000000..1309851520f
--- /dev/null
+++ b/resources/commands/header.md
@@ -0,0 +1,16 @@
+---
+title: Metabase CLI
+description: CLI commands for managing your Metabase instance, including database migrations, serialization, and administrative tasks.
+---
+
+# Metabase CLI
+
+Metabase ships with some handy CLI commands for administration, maintenance, and automation tasks. These commands let you manage your Metabase instance, migrate databases, handle serialization, and generate documentation.
+
+To view a list of commands, run the Metabase jar followed by `help`.
+
+```
+java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar help
+```
+
+Metabase will print out the help text for available commands.
diff --git a/src/metabase/cmd/command_dox.clj b/src/metabase/cmd/command_dox.clj
new file mode 100644
index 00000000000..bf650e2b404
--- /dev/null
+++ b/src/metabase/cmd/command_dox.clj
@@ -0,0 +1,125 @@
+(ns metabase.cmd.command-dox
+ "Generate CLI command documentation by running
+
+ clojure -M:run command-documentation
+
+ or
+
+ java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar command-documentation"
+ (:require
+ [clojure.string :as str]
+ [metabase.cmd.common :as cmd.common]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private section-separator
+ "Separator between major sections in generated documentation"
+ "\n\n")
+
+(def ^:private document-ending
+ "Trailing newline at end of document"
+ "\n")
+
+(defn- command?
+ "Returns true if the var has :command metadata"
+ [[_symb varr]]
+ (-> varr meta :command boolean))
+
+(defn- command-vars
+ "Returns a sorted sequence of [symbol var] pairs for all commands in metabase.cmd.core"
+ []
+ (require 'metabase.cmd.core)
+ (->> (ns-interns 'metabase.cmd.core)
+ (filter command?)
+ (sort-by first)))
+
+(defn- format-arglist
+ "Format an arglist for display in markdown"
+ [command-name arglist]
+ (let [args (->> arglist
+ (remove #{'&})
+ (str/join " "))]
+ (cond-> command-name
+ (seq args) (str " " args))))
+
+(defn- format-arglists
+ "Format all arglists for a command, joined with ' | '"
+ [command-name arglists]
+ (->> arglists
+ (map #(format-arglist command-name %))
+ (str/join " | ")))
+
+(defn- format-option
+ "Format a single option spec as a markdown list item"
+ [[short-opt long-opt desc & _]]
+ (let [opt-str (->> [short-opt long-opt]
+ (remove str/blank?)
+ (str/join ", "))]
+ (format "- `%s` - %s" opt-str desc)))
+
+(defn- format-options
+ "Format the options section for a command"
+ [arg-spec]
+ (when (seq arg-spec)
+ (str "\n\nOptions:\n\n"
+ (str/join "\n" (map format-option arg-spec)))))
+
+(defn- normalize-whitespace
+ "Normalize whitespace in a string by replacing multiple spaces and newlines with single spaces"
+ [s]
+ (-> s
+ str/trim
+ (str/replace #"\s+" " ")))
+
+(defn- format-description
+ "Format a docstring as markdown description"
+ [doc]
+ (some-> doc
+ normalize-whitespace
+ (->> (str "\n\n"))))
+
+(defn- format-command
+ "Generate markdown documentation for a single command"
+ [[symb varr]]
+ (let [{:keys [doc arg-spec arglists]} (meta varr)
+ command-name (name symb)
+ heading (str "## `" (format-arglists command-name arglists) "`")]
+ (str heading
+ (format-description doc)
+ (format-options arg-spec))))
+
+(defn- generate-commands-section
+ "Generate the commands section of the documentation"
+ []
+ (->> (command-vars)
+ (map format-command)
+ (str/join section-separator)))
+
+(defn- header-section
+ "Generate the header section of the documentation"
+ []
+ (cmd.common/load-resource! "commands/header.md"))
+
+(defn- footer-section
+ "Generate the footer section with additional useful commands"
+ []
+ (cmd.common/load-resource! "commands/footer.md"))
+
+(defn- generate-documentation
+ "Generate the complete commands documentation"
+ []
+ (str/join section-separator
+ [(header-section)
+ (generate-commands-section)
+ (str (footer-section) document-ending)]))
+
+(defn generate-dox!
+ "Generates CLI command documentation and writes it to docs/installation-and-operation/commands.md"
+ ([]
+ (generate-dox! "docs/installation-and-operation/commands.md"))
+ ([^String output-file]
+ (printf "Generating CLI command documentation in %s\n" output-file)
+ (let [content (generate-documentation)]
+ (cmd.common/write-doc-file! output-file content)
+ (printf "Wrote commands documentation to %s\n" output-file))
+ (println "Done.")))
diff --git a/src/metabase/cmd/core.clj b/src/metabase/cmd/core.clj
index ab991034323..43b60137300 100644
--- a/src/metabase/cmd/core.clj
+++ b/src/metabase/cmd/core.clj
@@ -160,6 +160,13 @@
(classloader/require 'metabase.cmd.config-file-gen)
((resolve 'metabase.cmd.config-file-gen/generate-config-file-doc!)))
+(defn ^:command command-documentation
+ "Generates a markdown file containing documentation for all CLI commands. This is written to a file called
+ `docs/installation-and-operation/commands.md`."
+ []
+ (classloader/require 'metabase.cmd.command-dox)
+ ((resolve 'metabase.cmd.command-dox/generate-dox!)))
+
(defn ^:command driver-methods
"Print a list of all multimethods available for a driver to implement, optionally with their docstrings."
([]
diff --git a/test/metabase/cmd/command_dox_test.clj b/test/metabase/cmd/command_dox_test.clj
new file mode 100644
index 00000000000..f233cabcfff
--- /dev/null
+++ b/test/metabase/cmd/command_dox_test.clj
@@ -0,0 +1,168 @@
+(ns metabase.cmd.command-dox-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.cmd.command-dox :as sut]))
+
+(deftest ^:parallel format-arglist-test
+ (testing "format-arglist handles various arglist patterns"
+ (testing "command with no args"
+ (is (= "test-command" (#'sut/format-arglist "test-command" []))))
+ (testing "command with single arg"
+ (is (= "test-command arg1" (#'sut/format-arglist "test-command" '[arg1]))))
+ (testing "command with multiple args"
+ (is (= "test-command arg1 arg2" (#'sut/format-arglist "test-command" '[arg1 arg2]))))
+ (testing "command with varargs removes & symbol"
+ (is (= "test-command arg1 options" (#'sut/format-arglist "test-command" '[arg1 & options]))))))
+
+(deftest ^:parallel format-arglists-test
+ (testing "format-arglists joins multiple arglists with |"
+ (testing "single arglist"
+ (is (= "command arg" (#'sut/format-arglists "command" '([arg])))))
+ (testing "multiple arglists"
+ (is (= "command | command arg" (#'sut/format-arglists "command" '([] [arg])))))
+ (testing "multiple arglists with various args"
+ (is (= "command arg1 | command arg1 arg2"
+ (#'sut/format-arglists "command" '([arg1] [arg1 arg2])))))))
+
+(deftest ^:parallel format-option-test
+ (testing "format-option handles option specs correctly"
+ (testing "short and long option"
+ (is (= "- `-k, --keep-existing` - Do not delete target file"
+ (#'sut/format-option ["-k" "--keep-existing" "Do not delete target file"]))))
+ (testing "long option only"
+ (is (= "- `--full-stacktrace` - Output full stacktraces"
+ (#'sut/format-option [nil "--full-stacktrace" "Output full stacktraces"]))))
+ (testing "short option only"
+ (is (= "- `-e` - Continue on error"
+ (#'sut/format-option ["-e" nil "Continue on error"]))))
+ (testing "option with additional metadata is ignored"
+ (is (= "- `-c, --collection` - Export only specified IDs"
+ (#'sut/format-option ["-c" "--collection" "Export only specified IDs" :id :collection-ids]))))
+ (testing "empty string for short option should be ignored"
+ (is (= "- `--full-stacktrace` - Output full stacktraces"
+ (#'sut/format-option ["" "--full-stacktrace" "Output full stacktraces"]))))
+ (testing "empty string for long option should be ignored"
+ (is (= "- `-e` - Continue on error"
+ (#'sut/format-option ["-e" "" "Continue on error"]))))
+ (testing "both options as empty strings should handle gracefully"
+ (is (= "- `` - Some description"
+ (#'sut/format-option ["" "" "Some description"]))))))
+
+(deftest ^:parallel format-options-test
+ (testing "format-options handles option specs"
+ (testing "empty options returns nil"
+ (is (nil? (#'sut/format-options []))))
+ (testing "single option"
+ (let [result (#'sut/format-options [["-k" "--keep-existing" "Do not delete"]])]
+ (is (str/includes? result "Options:"))
+ (is (str/includes? result "- `-k, --keep-existing` - Do not delete"))))
+ (testing "multiple options"
+ (let [result (#'sut/format-options [["-k" "--keep-existing" "Do not delete"]
+ ["-p" "--dump-plaintext" "Do not encrypt"]])]
+ (is (str/includes? result "Options:"))
+ (is (str/includes? result "- `-k, --keep-existing` - Do not delete"))
+ (is (str/includes? result "- `-p, --dump-plaintext` - Do not encrypt"))))))
+
+(deftest ^:parallel normalize-whitespace-test
+ (testing "normalize-whitespace handles various whitespace patterns"
+ (testing "collapses multiple spaces to single space"
+ (is (= "foo bar baz" (#'sut/normalize-whitespace "foo bar baz"))))
+ (testing "collapses newlines to single space"
+ (is (= "foo bar baz" (#'sut/normalize-whitespace "foo\nbar\nbaz"))))
+ (testing "collapses mixed whitespace to single space"
+ (is (= "foo bar baz" (#'sut/normalize-whitespace "foo\n bar\n\n baz"))))
+ (testing "trims leading and trailing whitespace"
+ (is (= "foo bar" (#'sut/normalize-whitespace " foo bar "))))
+ (testing "handles tabs"
+ (is (= "foo bar" (#'sut/normalize-whitespace "foo\tbar"))))))
+
+(deftest ^:parallel format-command-test
+ (testing "format-command generates markdown for a command"
+ (testing "command with no args or options"
+ (let [command-var (with-meta
+ (fn [] nil)
+ {:arglists '([])
+ :doc "Print version information"})
+ result (#'sut/format-command ['version command-var])]
+ (is (str/starts-with? result "## `version`"))
+ (is (str/includes? result "Print version information"))
+ (is (not (str/includes? result "Options:")))))
+ (testing "command with args but no options"
+ (let [command-var (with-meta
+ (fn [_] nil)
+ {:arglists '([direction])
+ :doc "Run database migrations"})
+ result (#'sut/format-command ['migrate command-var])]
+ (is (str/starts-with? result "## `migrate direction`"))
+ (is (str/includes? result "Run database migrations"))
+ (is (not (str/includes? result "Options:")))))
+ (testing "command with multiple arglists"
+ (let [command-var (with-meta
+ (fn
+ ([] nil)
+ ([_] nil))
+ {:arglists '([] [h2-connection-string])
+ :doc "Transfer data from H2"})
+ result (#'sut/format-command ['load-from-h2 command-var])]
+ (is (str/starts-with? result "## `load-from-h2 | load-from-h2 h2-connection-string`"))
+ (is (str/includes? result "Transfer data from H2"))))
+ (testing "command with options"
+ (let [command-var (with-meta
+ (fn [_ & _] nil)
+ {:arglists '([h2-filename & opts])
+ :doc "Transfer data to H2"
+ :arg-spec [["-k" "--keep-existing" "Do not delete target file"]]})
+ result (#'sut/format-command ['dump-to-h2 command-var])]
+ (is (str/starts-with? result "## `dump-to-h2 h2-filename opts`"))
+ (is (str/includes? result "Transfer data to H2"))
+ (is (str/includes? result "Options:"))
+ (is (str/includes? result "- `-k, --keep-existing` - Do not delete target file"))))
+ (testing "command with multiline docstring normalizes whitespace"
+ (let [command-var (with-meta
+ (fn [] nil)
+ {:arglists '([])
+ :doc "This is a command\n with multiple lines\n and extra spacing"})
+ result (#'sut/format-command ['test-cmd command-var])]
+ (is (str/starts-with? result "## `test-cmd`"))
+ (is (str/includes? result "This is a command with multiple lines and extra spacing"))
+ (is (not (str/includes? result "\n with")))))))
+
+(deftest ^:parallel command-vars-test
+ (testing "command-vars returns commands from metabase.cmd.core"
+ (let [commands (#'sut/command-vars)]
+ (testing "returns a sequence of [symbol var] pairs"
+ (is (sequential? commands))
+ (is (every? (fn [[symb varr]]
+ (and (symbol? symb)
+ (var? varr)))
+ commands)))
+ (testing "all returned vars have :command metadata"
+ (is (every? (fn [[_symb varr]]
+ (:command (meta varr)))
+ commands)))
+ (testing "includes expected commands"
+ (let [command-names (set (map (comp name first) commands))]
+ (is (contains? command-names "version"))
+ (is (contains? command-names "help"))
+ (is (contains? command-names "migrate"))
+ (is (contains? command-names "command-documentation"))))
+ (testing "commands are sorted by name"
+ (let [command-names (map (comp name first) commands)]
+ (is (= command-names (sort command-names))))))))
+
+(deftest generate-documentation-test
+ (testing "generate-documentation produces complete markdown document"
+ (let [doc (with-redefs [sut/header-section (constantly "# Test Header")
+ sut/footer-section (constantly "# Test Footer")]
+ (#'sut/generate-documentation))]
+ (testing "includes header"
+ (is (str/starts-with? doc "# Test Header")))
+ (testing "includes footer"
+ (is (str/ends-with? (str/trim doc) "# Test Footer")))
+ (testing "includes command documentation"
+ (is (str/includes? doc "## `version`"))
+ (is (str/includes? doc "## `help")))
+ (testing "has proper spacing between sections"
+ (is (str/includes? doc "# Test Header\n\n##"))
+ (is (str/includes? doc ".\n\n# Test Footer"))))))