Group cli options in sections

workspace/lib/mix/tasks/workspace.check.ex

@@ -16,7 +16,7 @@ defmodule Mix.Tasks.Workspace.Check do
 
   ## Command Line Options
 
-  #{CliOptions.docs(@options_schema, sort: true)}
+  #{CliOptions.docs(@options_schema, sort: true, sections: Workspace.CliOptions.doc_sections())}
   """
 
   use Mix.Task

workspace/lib/mix/tasks/workspace.graph.ex

@@ -26,7 +26,8 @@ defmodule Mix.Tasks.Workspace.Graph do
       doc: """
       If set the project's tags are also included in the generated graph. Currently
       applicable only for `:pretty` and `:plain` formatters.
-      """
+      """,
+      doc_section: :display
     ],
     focus: [
       type: :string,
@@ -154,7 +155,7 @@ defmodule Mix.Tasks.Workspace.Graph do
 
   ## Command Line Options
 
-  #{CliOptions.docs(@options_schema, sort: true)}
+  #{CliOptions.docs(@options_schema, sort: true, sections: Workspace.CliOptions.doc_sections())}
   """
   use Mix.Task
   alias Workspace.Graph.Formatter

workspace/lib/mix/tasks/workspace.list.ex

@@ -8,29 +8,33 @@ defmodule Mix.Tasks.Workspace.List do
       associated metadata. By default it will be saved in `workspace.json` in the
       current directory. You can override the output path by setting the `--output`
       option.
-      """
+      """,
+      doc_section: :export
     ],
     output: [
       type: :string,
       default: "workspace.json",
       doc: """
       The output file. Applicable only if `--json` is set.
-      """
+      """,
+      doc_section: :export
     ],
     relative_paths: [
       type: :boolean,
       default: false,
       doc: """
       If set the paths in the exported json file will be relative with respect to the
       workspace path. Applicable only if `--json` is set.
-      """
+      """,
+      doc_section: :export
     ],
     maintainer: [
       type: :string,
       doc: """
       Search for projects with the given maintainer. A partial case insensitive string search
       is performed so you can provide only part of the maintainer's name.
-      """
+      """,
+      doc_section: :filtering
     ]
   ]
 
@@ -63,7 +67,7 @@ defmodule Mix.Tasks.Workspace.List do
 
   ## Command line options
 
-  #{CliOptions.docs(@options_schema, sort: true)}
+  #{CliOptions.docs(@options_schema, sort: true, sections: Workspace.CliOptions.doc_sections())}
 
   ## Filtering projects
 

workspace/lib/mix/tasks/workspace.run.ex

@@ -8,7 +8,8 @@ defmodule Mix.Tasks.Workspace.Run do
     ],
     only_roots: [
       type: :boolean,
-      doc: "If set, the task will be executed only on graph's root nodes."
+      doc: "If set, the task will be executed only on graph's root nodes.",
+      doc_section: :status
     ],
     dry_run: [
       type: :boolean,
@@ -56,7 +57,8 @@ defmodule Mix.Tasks.Workspace.Run do
       generated with the run results for each project. This may be useful for
       your CI/CD automation pipelines, in case you want to post-process the
       run results.
-      """
+      """,
+      doc_section: :export
     ]
   ]
 
@@ -104,7 +106,7 @@ defmodule Mix.Tasks.Workspace.Run do
       
   ## Command-line Options
 
-  #{CliOptions.docs(@options_schema, sort: true)}
+  #{CliOptions.docs(@options_schema, sort: true, sections: Workspace.CliOptions.doc_sections())}
 
   ## Filtering runs
 

workspace/lib/mix/tasks/workspace.status.ex

@@ -15,7 +15,7 @@ defmodule Mix.Tasks.Workspace.Status do
 
   ## Command line options
 
-  #{CliOptions.docs(@options_schema, sort: true)}
+  #{CliOptions.docs(@options_schema, sort: true, sections: Workspace.CliOptions.doc_sections())}
   """
   use Mix.Task
 

workspace/lib/mix/tasks/workspace.test.coverage.ex

@@ -5,7 +5,8 @@ defmodule Mix.Tasks.Workspace.Test.Coverage do
       doc: """
       If set to true only the package coverage is reported and not the individual modules
       coverages. This has higher priority than the `:verbose` option.
-      """
+      """,
+      doc_section: :display
     ]
   ]
 
@@ -200,7 +201,7 @@ defmodule Mix.Tasks.Workspace.Test.Coverage do
 
   ## Command line options
 
-  #{CliOptions.docs(@options_schema, sort: true)}
+  #{CliOptions.docs(@options_schema, sort: true, sections: Workspace.CliOptions.doc_sections())}
   """
   use Mix.Task
 

workspace/lib/workspace/cli_options.ex

@@ -8,13 +8,15 @@ defmodule Workspace.CliOptions do
       multiple: true,
       short: "p",
       doc:
-        "The project name, can be defined multiple times. If not set all projects are considered"
+        "The project name, can be defined multiple times. If not set all projects are considered",
+      doc_section: :filtering
     ],
     exclude: [
       type: :string,
       short: "e",
       multiple: true,
-      doc: "Ignore the given projects"
+      doc: "Ignore the given projects",
+      doc_section: :filtering
     ],
     tags: [
       type: :string,
@@ -24,7 +26,8 @@ defmodule Workspace.CliOptions do
       If set, only projects with the given tag(s) will be considered. For scoped tags you should
       provide a colon separated string (examples: `shared`, `scope:api`, `type:utils`). For
       excluding a specific tag use `--exclude-tag`
-      """
+      """,
+      doc_section: :filtering
     ],
     excluded_tags: [
       type: :string,
@@ -34,49 +37,58 @@ defmodule Workspace.CliOptions do
       If set, any projects with any of the given tag(s) will be excluded. For scoped tags you should
       provide a colon separated string (examples: `shared`, `scope:api`, `type:utils`). For selecting
       a specific tag use `--tag`
-      """
+      """,
+      doc_section: :filtering
     ],
     affected: [
       type: :boolean,
       short: "a",
-      doc: "Run only on affected projects"
+      doc: "Run only on affected projects",
+      doc_section: :status
     ],
     modified: [
       type: :boolean,
       short: "m",
-      doc: "Run only on modified projects"
+      doc: "Run only on modified projects",
+      doc_section: :status
     ],
     verbose: [
       type: :boolean,
-      doc: "If set enables verbose logging"
+      doc: "If set enables verbose logging",
+      doc_section: :display
     ],
     workspace_path: [
       type: :string,
-      doc: "If set it specifies the root workspace path, defaults to current directory"
+      doc: "If set it specifies the root workspace path, defaults to current directory",
+      doc_section: :workspace
     ],
     config_path: [
       type: :string,
       doc: "The path to the workspace config to be used, relative to the workspace path",
-      default: ".workspace.exs"
+      default: ".workspace.exs",
+      doc_section: :workspace
     ],
     show_status: [
       type: :boolean,
       default: false,
-      doc: "If set the status of each project will be included in the output graph"
+      doc: "If set the status of each project will be included in the output graph",
+      doc_section: :display
     ],
     base: [
       type: :string,
       doc: """
       The base git reference to compare the head to. Applied only when `--affected` or `--modified`
       are set.
-      """
+      """,
+      doc_section: :status
     ],
     head: [
       type: :string,
       default: "HEAD",
       doc: """
       A reference to the git head. Applied only if `--base` is set for getting the changed files
-      """
+      """,
+      doc_section: :status
     ]
   ]
 
@@ -87,4 +99,30 @@ defmodule Workspace.CliOptions do
   @doc false
   @spec option(key :: atom()) :: keyword()
   def option(key), do: Keyword.fetch!(@default_cli_options, key)
+
+  @doc false
+  @spec doc_sections() :: keyword()
+  def doc_sections do
+    [
+      status: [
+        header: "Workspace status options",
+        doc: """
+        Status is retrieved from the diff between the given `--base` and `--head`. Knowing the
+        changed files we can limit the execution of workspace commands only to relevant projects.
+        """
+      ],
+      filtering: [
+        header: "Filtering options"
+      ],
+      display: [
+        header: "Display options"
+      ],
+      export: [
+        header: "Export options"
+      ],
+      workspace: [
+        header: "Global workspace options"
+      ]
+    ]
+  end
 end