diff --git a/workspace/lib/mix/tasks/workspace.check.ex b/workspace/lib/mix/tasks/workspace.check.ex index 5c53caa..e5d0d80 100644 --- a/workspace/lib/mix/tasks/workspace.check.ex +++ b/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 diff --git a/workspace/lib/mix/tasks/workspace.graph.ex b/workspace/lib/mix/tasks/workspace.graph.ex index fafadcd..dafb8e7 100644 --- a/workspace/lib/mix/tasks/workspace.graph.ex +++ b/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 diff --git a/workspace/lib/mix/tasks/workspace.list.ex b/workspace/lib/mix/tasks/workspace.list.ex index ce189b5..409461b 100644 --- a/workspace/lib/mix/tasks/workspace.list.ex +++ b/workspace/lib/mix/tasks/workspace.list.ex @@ -8,14 +8,16 @@ 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, @@ -23,14 +25,16 @@ defmodule Mix.Tasks.Workspace.List do 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 diff --git a/workspace/lib/mix/tasks/workspace.run.ex b/workspace/lib/mix/tasks/workspace.run.ex index 6e9e115..691bd15 100644 --- a/workspace/lib/mix/tasks/workspace.run.ex +++ b/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 diff --git a/workspace/lib/mix/tasks/workspace.status.ex b/workspace/lib/mix/tasks/workspace.status.ex index c1d82d7..b9c74e1 100644 --- a/workspace/lib/mix/tasks/workspace.status.ex +++ b/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 diff --git a/workspace/lib/mix/tasks/workspace.test.coverage.ex b/workspace/lib/mix/tasks/workspace.test.coverage.ex index 94c7068..d9b7a2f 100644 --- a/workspace/lib/mix/tasks/workspace.test.coverage.ex +++ b/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 diff --git a/workspace/lib/workspace/cli_options.ex b/workspace/lib/workspace/cli_options.ex index 528af91..51cd1cf 100644 --- a/workspace/lib/workspace/cli_options.ex +++ b/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