Merge branch 'aevri/doc_artifact_log' into 'master'

'artifact log': document the 'artifacts' argument

See merge request BuildStream/buildstream!1223

1 files changed, 37 insertions, 2 deletions

diff --git a/buildstream/_frontend/cli.py b/buildstream/_frontend/cli.py
index 5681fd103..74a529934 100644
--- a/buildstream/_frontend/cli.py
+++ b/buildstream/_frontend/cli.py
@@ -1084,11 +1084,46 @@ def artifact_push(app, elements, deps, remote):
 ################################################################
 #                     Artifact Log Command                     #
 ################################################################
-@artifact.command(name='log', short_help="Show logs of an artifact")
+@artifact.command(name='log', short_help="Show logs of artifacts")
 @click.argument('artifacts', type=click.Path(), nargs=-1)
 @click.pass_obj
 def artifact_log(app, artifacts):
-    """Show logs of all artifacts"""
+    """Show logs of artifacts.
+
+    Note that 'artifacts' can be element references like "hello.bst", and they
+    can also be artifact references. You may use shell-style wildcards for
+    either.
+
+    Here are some examples of element references:
+
+    \b
+    - `hello.bst`
+    - `*.bst`
+
+    Note that element references must end with '.bst' to distinguish them from
+    artifact references. Anything that does not end in '.bst' is an artifact
+    ref.
+
+    Artifact references follow the format `<project_name>/<element>/<key>`.
+    Note that 'element' is without the `.bst` extension.
+
+    Here are some examples of artifact references:
+
+    \b
+    - `myproject/hello/*`
+    - `myproject/*`
+    - `*`
+    - `myproject/hello/827637*`
+    - `myproject/he*/827637*`
+    - `myproject/he??o/827637*`
+    - `m*/h*/8276376b077eda104c812e6ec2f488c7c9eea211ce572c83d734c10bf241209f`
+
+    """
+    # Note that the backticks in the above docstring are important for the
+    # generated docs. When sphinx is generating rst output from the help output
+    # of this command, the asterisks will be interpreted as emphasis tokens if
+    # they are not somehow escaped.
+
     with app.initialized():
         logsdirs = app.stream.artifact_log(artifacts)