Conan commands docstrings (#13176)

conan/cli/args.py

@@ -102,7 +102,7 @@ def add_reference_args(parser):
     parser.add_argument("--user", action=OnceArgument,
                         help='Provide a user if not specified in conanfile')
     parser.add_argument("--channel", action=OnceArgument,
-                        help='Provide a channel if not specified in conanfil')
+                        help='Provide a channel if not specified in conanfile')
 
 
 def common_graph_args(subparser):

conan/cli/commands/build.py

@@ -12,7 +12,7 @@
 @conan_command(group='Creator')
 def build(conan_api, parser, *args):
     """
-    Install dependencies and calls the build() method
+    Install dependencies and calls the build() method.
     """
     parser.add_argument("path", nargs="?",
                         help="Path to a folder containing a recipe (conanfile.py "

conan/cli/commands/cache.py

@@ -9,19 +9,20 @@
 
 @conan_command(group="Consumer")
 def cache(conan_api: ConanAPI, parser, *args):
-    """Performs file operations in the local cache (of recipes and packages)
+    """
+    Perform file operations in the local cache (of recipes and/or packages).
     """
     pass
 
 
 @conan_subcommand(formatters={"text": default_text_formatter})
 def cache_path(conan_api: ConanAPI, parser, subparser, *args):
     """
-        Shows the path in the Conan cache af a given reference
+    Show the path to the Conan cache for a given reference.
     """
     subparser.add_argument("reference", help="Recipe reference or Package reference")
     subparser.add_argument("--folder", choices=['export_source', 'source', 'build'],
-                           help="Show the path to the specified element. The 'build'"
+                           help="Path to show. The 'build'"
                                 " requires a package reference. If not specified it shows 'exports'"
                                 " path ")
 
@@ -54,22 +55,23 @@ def cache_path(conan_api: ConanAPI, parser, subparser, *args):
 @conan_subcommand()
 def cache_clean(conan_api: ConanAPI, parser, subparser, *args):
     """
-        Shows the path in the Conan cache af a given reference
+    Remove non-critical folders from the cache, like source, build and/or download
+    (.tgz store) ones.
     """
-    subparser.add_argument("pattern", help="selection pattern for references to clean")
+    subparser.add_argument("pattern", help="Selection pattern for references to clean")
     subparser.add_argument("-s", "--source", action='store_true', default=False,
                            help="Clean source folders")
     subparser.add_argument("-b", "--build", action='store_true', default=False,
-                           help="Clean source folders")
+                           help="Clean build folders")
     subparser.add_argument("-d", "--download", action='store_true', default=False,
                            help="Clean download folders")
     subparser.add_argument('-p', '--package-query', action=OnceArgument,
-                           help="Remove all packages (empty) or provide a query: "
+                           help="Remove only the packages matching a specific query, e.g., "
                                 "os=Windows AND (arch=x86 OR compiler=gcc)")
     args = parser.parse_args(*args)
 
     if not args.source and not args.build and not args.download:
-        raise ConanException("Define at least one argument from --source, --build, --download")
+        raise ConanException("Define at least one argument among [--source, --build, --download]")
 
     ref_pattern = ListPattern(args.pattern, rrev="*", package_id="*", prev="*")
     package_list = conan_api.list.select(ref_pattern, package_query=args.package_query)

conan/cli/commands/config.py

@@ -10,14 +10,15 @@
 @conan_command(group='Consumer')
 def config(conan_api, parser, *args):
     """
-    Manages the Conan configuration in the current Conan home.
+    Manage the Conan configuration in the Conan home.
     """
 
 
 @conan_subcommand()
 def config_install(conan_api, parser, subparser, *args):
     """
-    Installs the configuration (remotes, profiles, conf), from git, http or folder
+    Install the configuration (remotes, profiles, conf), from git, http or a folder, into the
+    Conan home folder.
     """
     subparser.add_argument("item",
                            help="git repository, local file or folder or zip file (local or "
@@ -50,14 +51,14 @@ def list_text_formatter(confs):
 @conan_subcommand(formatters={"text": default_text_formatter})
 def config_home(conan_api, parser, subparser, *args):
     """
-    Gets the Conan home folder
+    Show the Conan home folder.
     """
     return conan_api.config.home()
 
 
 @conan_subcommand(formatters={"text": list_text_formatter, "json": default_json_formatter})
 def config_list(conan_api, parser, subparser, *args):
     """
-    Prints all the Conan available configurations: core and tools.
+    Show all the Conan available configurations: core and tools.
     """
     return BUILT_IN_CONFS

conan/cli/commands/create.py

@@ -23,13 +23,13 @@ def json_create(deps_graph):
 @conan_command(group="Creator", formatters={"json": json_create})
 def create(conan_api, parser, *args):
     """
-    Create a package
+    Create a package.
     """
     common_args_export(parser)
     add_lockfile_args(parser)
     add_common_install_arguments(parser)
     parser.add_argument("--build-require", action='store_true', default=False,
-                        help='The provided reference is a build-require')
+                        help='Whether the provided reference is a build-require')
     parser.add_argument("-tf", "--test-folder", action=OnceArgument,
                         help='Alternative test folder name. By default it is "test_package". '
                              'Use "" to skip the test stage')

conan/cli/commands/editable.py

@@ -9,15 +9,15 @@
 @conan_command(group="Creator")
 def editable(conan_api, parser, *args):
     """
-    Allows working with a package in user folder
+    Allows working with a package in user folder.
     """
 
 
 @conan_subcommand()
 def editable_add(conan_api, parser, subparser, *args):
     """
     Define the given <path> location as the package <reference>, so when this
-    package is required, it is used from this <path> location instead of from the cache
+    package is required, it is used from this <path> location instead of from the cache.
     """
     subparser.add_argument('path', help='Path to the package folder in the user workspace')
     add_reference_args(subparser)
@@ -69,7 +69,7 @@ def print_editables_text(data):
 @conan_subcommand(formatters={"text": print_editables_text, "json": print_editables_json})
 def editable_list(conan_api, parser, subparser, *args):
     """
-    List packages in editable mode
+    List all the packages in editable mode.
     """
     editables = conan_api.local.editable_list()
     return editables

conan/cli/commands/export.py

@@ -18,7 +18,7 @@ def json_export(ref):
 @conan_command(group="Creator", formatters={"json": json_export})
 def export(conan_api, parser, *args):
     """
-    Export recipe to the Conan package cache
+    Export recipe to the Conan package cache.
     """
     common_args_export(parser)
     group = parser.add_mutually_exclusive_group()
@@ -33,7 +33,7 @@ def export(conan_api, parser, *args):
     parser.add_argument("--lockfile-partial", action="store_true",
                         help="Do not raise an error if some dependency is not found in lockfile")
     parser.add_argument("--build-require", action='store_true', default=False,
-                        help='The provided reference is a build-require')
+                        help='Whether the provided reference is a build-require')
     args = parser.parse_args(*args)
 
     cwd = os.getcwd()

conan/cli/commands/export_pkg.py

@@ -17,13 +17,13 @@ def json_export_pkg(info):
 @conan_command(group="Creator", formatters={"json": json_export_pkg})
 def export_pkg(conan_api, parser, *args):
     """
-    Create a package directly from pre-compiled binaries
+    Create a package directly from pre-compiled binaries.
     """
     parser.add_argument("path", help="Path to a folder containing a recipe (conanfile.py)")
     parser.add_argument("-of", "--output-folder",
                         help='The root output folder for generated and build files')
     parser.add_argument("--build-require", action='store_true', default=False,
-                        help='The provided reference is a build-require')
+                        help='Whether the provided reference is a build-require')
     parser.add_argument("-tf", "--test-folder", action=OnceArgument,
                         help='Alternative test folder name. By default it is "test_package". '
                              'Use "" to skip the test stage')

conan/cli/commands/graph.py

@@ -16,7 +16,7 @@
 @conan_command(group="Consumer")
 def graph(conan_api, parser, *args):
     """
-    Computes a dependency graph, without  installing or building the binaries
+    Compute a dependency graph, without installing or building the binaries.
     """
 
 
@@ -36,7 +36,7 @@ def json_build_order(build_order):
 @conan_subcommand(formatters={"text": cli_build_order, "json": json_build_order})
 def graph_build_order(conan_api, parser, subparser, *args):
     """
-    Computes the build order of a dependency graph
+    Compute the build order of a dependency graph.
     """
     common_graph_args(subparser)
     args = parser.parse_args(*args)
@@ -86,7 +86,7 @@ def graph_build_order(conan_api, parser, subparser, *args):
 @conan_subcommand(formatters={"text": cli_build_order, "json": json_build_order})
 def graph_build_order_merge(conan_api, parser, subparser, *args):
     """
-    Merges more than 1 build-order file
+    Merge more than 1 build-order file.
     """
     subparser.add_argument("--file", nargs="?", action="append", help="Files to be merged")
     args = parser.parse_args(*args)
@@ -107,10 +107,11 @@ def graph_build_order_merge(conan_api, parser, subparser, *args):
                               "dot": format_graph_dot})
 def graph_info(conan_api, parser, subparser, *args):
     """
-    Computes the dependency graph and shows information about it
+    Compute the dependency graph and shows information about it.
     """
     common_graph_args(subparser)
-    subparser.add_argument("--check-updates", default=False, action="store_true")
+    subparser.add_argument("--check-updates", default=False, action="store_true",
+                           help="Check if there are recipe updates")
     subparser.add_argument("--filter", action="append",
                            help="Show only the specified fields")
     subparser.add_argument("--package-filter", action="append",

conan/cli/commands/inspect.py

@@ -21,7 +21,7 @@ def inspect_text_formatter(data):
 @conan_command(group="Consumer", formatters={"text": inspect_text_formatter, "json": default_json_formatter})
 def inspect(conan_api, parser, *args):
     """
-    Inspect a conanfile.py to return the public fields
+    Inspect a conanfile.py to return the public fields.
     """
     parser.add_argument("path", help="Path to a folder containing a recipe (conanfile.py)")
 

conan/cli/commands/install.py

@@ -18,7 +18,7 @@ def json_install(info):
 @conan_command(group="Consumer", formatters={"json": json_install})
 def install(conan_api, parser, *args):
     """
-    Installs the requirements specified in a recipe (conanfile.py or conanfile.txt).
+    Install the requirements specified in a recipe (conanfile.py or conanfile.txt).
 
     It can also be used to install a concrete package specifying a
     reference. If any requirement is not found in the local cache, it will

conan/cli/commands/list.py

@@ -91,16 +91,16 @@ def print_list_json(data):
                                              "html": list_packages_html})
 def list(conan_api: ConanAPI, parser, *args):
     """
-    Lists existing recipes, revisions or packages in the cache or in remotes
+    List existing recipes, revisions, or packages in the cache (by default) or the remotes.
     """
     parser.add_argument('reference', help="Recipe reference or package reference. "
                                           "Both can contain * as wildcard at any reference field. "
                                           "If revision is not specified, it is assumed latest one.")
     parser.add_argument('-p', '--package-query', default=None, action=OnceArgument,
-                        help="Only list packages matching a specific query. e.g: os=Windows AND "
+                        help="List only the packages matching a specific query, e.g, os=Windows AND "
                              "(arch=x86 OR compiler=gcc)")
     parser.add_argument("-r", "--remote", default=None, action="append",
-                        help="Remote names. Accepts wildcards")
+                        help="Remote names. Accepts wildcards ('*' means all the remotes available)")
     parser.add_argument("-c", "--cache", action='store_true', help="Search in the local cache")
 
     args = parser.parse_args(*args)

conan/cli/commands/lock.py

@@ -13,14 +13,14 @@
 @conan_command(group="Consumer")
 def lock(conan_api, parser, *args):
     """
-    Create or manages lockfiles
+    Create or manages lockfiles.
     """
 
 
 @conan_subcommand()
 def lock_create(conan_api, parser, subparser, *args):
     """
-    Create a lockfile from a conanfile or a reference
+    Create a lockfile from a conanfile or a reference.
     """
     common_graph_args(subparser)
     args = parser.parse_args(*args)
@@ -63,7 +63,7 @@ def lock_create(conan_api, parser, subparser, *args):
 @conan_subcommand()
 def lock_merge(conan_api, parser, subparser, *args):
     """
-    Merge 2 or more lockfiles
+    Merge 2 or more lockfiles.
     """
     subparser.add_argument('--lockfile', action="append", help='Path to lockfile to be merged')
     subparser.add_argument("--lockfile-out", action=OnceArgument, default=LOCKFILE,
@@ -88,7 +88,7 @@ def lock_add(conan_api, parser, subparser, *args):
     Add requires, build-requires or python-requires to existing or new lockfile. Resulting lockfile
     will be ordereded, newer versions/revisions first.
     References can be with our without revisions like "--requires=pkg/version", but they
-    must be package references, including at least the version, they cannot contain a version range
+    must be package references, including at least the version, they cannot contain a version range.
     """
     subparser.add_argument('--requires', action="append", help='Add references to lockfile.')
     subparser.add_argument('--build-requires', action="append",

conan/cli/commands/new.py

@@ -24,7 +24,7 @@ def new(conan_api, parser, *args):
                         "as your template, or a path relative to your conan home folder."
                         )
     parser.add_argument("-d", "--define", action="append",
-                        help="Define a template argument as key=value")
+                        help="Define a template argument as key=value, e.g., -d name=mypkg")
     parser.add_argument("-f", "--force", action='store_true', help="Overwrite file if it already exists")
 
     args = parser.parse_args(*args)

conan/cli/commands/profile.py

@@ -30,7 +30,7 @@ def detected_profile_cli_output(detect_profile):
 @conan_subcommand(formatters={"text": print_profiles})
 def profile_show(conan_api, parser, subparser, *args):
     """
-    Show profiles
+    Show profiles.
     """
     add_profiles_args(subparser)
     args = parser.parse_args(*args)
@@ -41,7 +41,7 @@ def profile_show(conan_api, parser, subparser, *args):
 @conan_subcommand(formatters={"text": default_text_formatter})
 def profile_path(conan_api, parser, subparser, *args):
     """
-    Show profile path location
+    Show profile path location.
     """
     add_profiles_args(subparser)
     subparser.add_argument("name", help="Profile name")
@@ -52,7 +52,7 @@ def profile_path(conan_api, parser, subparser, *args):
 @conan_subcommand()
 def profile_detect(conan_api, parser, subparser, *args):
     """
-    Detect default profile
+    Detect default profile.
     """
     subparser.add_argument("--name", help="Profile name, 'default' if not specified")
     subparser.add_argument("-f", "--force", action='store_true', help="Overwrite if exists")
@@ -76,7 +76,7 @@ def profile_detect(conan_api, parser, subparser, *args):
 @conan_subcommand(formatters={"text": profiles_list_cli_output, "json": default_json_formatter})
 def profile_list(conan_api, parser, subparser, *args):
     """
-    List all profiles in the cache
+    List all profiles in the cache.
     """
     result = conan_api.profiles.list()
     return result
@@ -85,5 +85,5 @@ def profile_list(conan_api, parser, subparser, *args):
 @conan_command(group="Consumer")
 def profile(conan_api, parser, *args):
     """
-    Manages profiles
+    Manage profiles.
     """