Improve cli options docs generation

cli_options/lib/cli_options.ex

@@ -431,6 +431,13 @@ defmodule CliOptions do
 
     * `:sort` - if set to `true` the options will be sorted alphabetically.
   """
-  @spec docs(schema :: keyword(), opts :: keyword()) :: String.t()
-  def docs(schema, opts \\ []), do: CliOptions.Docs.generate(schema, opts)
+  @spec docs(schema :: keyword() | CliOptions.Schema.t(), opts :: keyword()) :: String.t()
+  def docs(schema, opts \\ [])
+
+  def docs(%CliOptions.Schema{} = schema, opts), do: CliOptions.Docs.generate(schema, opts)
+
+  def docs(schema, opts) when is_list(schema) do
+    schema = CliOptions.Schema.new!(schema)
+    docs(schema, opts)
+  end
 end

cli_options/lib/cli_options/docs.ex

@@ -2,9 +2,9 @@ defmodule CliOptions.Docs do
   @moduledoc false
 
   @doc false
-  @spec generate(schema :: keyword(), opts :: keyword()) :: String.t()
-  def generate(schema, opts) do
-    schema
+  @spec generate(schema :: CliOptions.Schema.t(), opts :: keyword()) :: String.t()
+  def generate(%CliOptions.Schema{} = schema, opts) do
+    schema.schema
     |> remove_hidden_options()
     |> maybe_sort(Keyword.get(opts, :sort, false))
     |> Enum.reduce([], &maybe_option_doc/2)
@@ -19,11 +19,7 @@ defmodule CliOptions.Docs do
   defp maybe_sort(schema, _other), do: schema
 
   defp maybe_option_doc({key, schema}, acc) do
-    if schema[:doc] == false do
-      acc
-    else
-      option_doc({key, schema}, acc)
-    end
+    option_doc({key, schema}, acc)
   end
 
   defp option_doc({key, schema}, acc) do
@@ -33,6 +29,7 @@ defmodule CliOptions.Docs do
         "`#{key_doc(key, schema)}`",
         "(`#{schema[:type]}`)",
         "-",
+        maybe_deprecated(schema),
         maybe_required(schema),
         key_body_doc(schema)
       ]
@@ -52,12 +49,19 @@ defmodule CliOptions.Docs do
   defp format_key(key), do: String.replace("#{key}", "_", "-")
 
   defp maybe_alias(schema) do
-    case schema[:alias] do
+    case schema[:short] do
       nil -> ""
       alias -> ", -#{alias}"
     end
   end
 
+  defp maybe_deprecated(schema) do
+    case schema[:deprecated] do
+      nil -> nil
+      message -> "*DEPRECATED #{message}*"
+    end
+  end
+
   defp maybe_required(schema) do
     case schema[:required] do
       true -> "Required. "
@@ -78,20 +82,21 @@ defmodule CliOptions.Docs do
       maybe_allowed(schema),
       maybe_default(schema)
     ]
-    |> Enum.join("")
+    |> Enum.reject(fn part -> is_nil(part) or part == "" end)
+    |> Enum.join(" ")
   end
 
   defp maybe_allowed(schema) do
     case schema[:allowed] do
       nil -> ""
-      allowed -> "   Allowed values: `#{inspect(allowed)}`."
+      allowed -> "Allowed values: `#{inspect(allowed)}`."
     end
   end
 
   defp maybe_default(schema) do
     case schema[:default] do
       nil -> ""
-      default -> "   [default: `#{default}`]"
+      default -> "[default: `#{default}`]"
     end
   end
 end

cli_options/lib/cli_options/schema.ex

@@ -111,7 +111,7 @@ defmodule CliOptions.Schema do
       type: :string,
       doc: """
       The documentation for the CLI option. Can be any markdown string. This will be
-      used in the automatically generate options documentation.
+      used in the automatically generated options documentation.
       """
     ],
     required: [

cli_options/test/cli_options/docs_test.exs

@@ -7,7 +7,7 @@ defmodule CliOptions.DocsTest do
     ],
     project: [
       type: :string,
-      alias: :p,
+      short: "p",
       required: true,
       doc: "The project to use",
       multiple: true
@@ -17,10 +17,6 @@ defmodule CliOptions.DocsTest do
       default: "parallel",
       allowed: ["parallel", "serial"]
     ],
-    ignore: [
-      type: :boolean,
-      doc: false
-    ],
     with_dash: [
       type: :boolean,
       doc: "a key with a dash"
@@ -35,10 +31,10 @@ defmodule CliOptions.DocsTest do
     test "test schema" do
       expected =
         """
-        * `--verbose` (`boolean`) -
+        * `--verbose` (`boolean`) - [default: `false`]
         * `--project, -p...` (`string`) - Required. The project to use
-        * `--mode` (`string`) -    Allowed values: `["parallel", "serial"]`.   [default: `parallel`]
-        * `--with-dash` (`boolean`) - a key with a dash
+        * `--mode` (`string`) - Allowed values: `["parallel", "serial"]`. [default: `parallel`]
+        * `--with-dash` (`boolean`) - a key with a dash [default: `false`]
         """
         |> String.trim()
 
@@ -48,14 +44,30 @@ defmodule CliOptions.DocsTest do
     test "with sorting enabled" do
       expected =
         """
-        * `--mode` (`string`) -    Allowed values: `["parallel", "serial"]`.   [default: `parallel`]
+        * `--mode` (`string`) - Allowed values: `["parallel", "serial"]`. [default: `parallel`]
         * `--project, -p...` (`string`) - Required. The project to use
-        * `--verbose` (`boolean`) -
-        * `--with-dash` (`boolean`) - a key with a dash
+        * `--verbose` (`boolean`) - [default: `false`]
+        * `--with-dash` (`boolean`) - a key with a dash [default: `false`]
         """
         |> String.trim()
 
       assert CliOptions.docs(@test_schema, sort: true) == expected
     end
+
+    test "prints deprecation info" do
+      schema = [
+        old: [type: :string, doc: "old option", deprecated: "use --new"],
+        new: [type: :string, doc: "new option"]
+      ]
+
+      expected =
+        """
+        * `--old` (`string`) - *DEPRECATED use --new* old option
+        * `--new` (`string`) - new option
+        """
+        |> String.trim()
+
+      assert CliOptions.docs(schema) == expected
+    end
   end
 end