'artifact log': document the 'artifacts' argumentaevri/doc_artifact_log

I found it quite difficult to guess what format the 'bst artifact log'
command would like artifact references in. Put them in the help for that
command, to save folks time.

In future work, we probably want to document the behaviour of
'Stream._classify_artifacts' globally - most commands take them and the
results can be surprising if you don't know about artifact refs.

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)