The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
generate command docs (#65608)
Jeff Bruemmer257f23f104cf
diff --git a/resources/commands/footer.md b/resources/commands/footer.mdnew file mode 100644index 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.mdnew file mode 100644index 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.cljnew file mode 100644index 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.cljindex 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.cljnew file mode 100644index 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"))))))