[buildstream] 02/08: doc: Documenting "artifact names".

[tv...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tvb pushed a commit to branch tristan/shell-artifacts
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit d33b29f27d0d22c55dd96157efaad7ef28a2d036
Author: Tristan van Berkom <tr...@codethink.co.uk>
AuthorDate: Tue Dec 8 16:51:35 2020 +0900

    doc: Documenting "artifact names".
    
    Added a description about artifact names at the beginning of the
    artifact commands section, along with a new glossary entry for
    artifact names which refers to the description.
---
 doc/source/main_glossary.rst  |  4 ++++
 doc/source/using_commands.rst | 23 +++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/doc/source/main_glossary.rst b/doc/source/main_glossary.rst
index aa0c6da..f1bf4cf 100644
--- a/doc/source/main_glossary.rst
+++ b/doc/source/main_glossary.rst
@@ -18,6 +18,10 @@ Glossary
        Artifacts can be built from :term:`Sources <Source>`, or pulled from a
        :term:`Remote Cache <Remote Cache>`, if available.
 
+   Artifact name
+       The :ref:`name of an artifact <artifact_names>`, which can be used
+       in various commands to operate directly on artifacts, without requiring
+       the use of a :term:`Project`.
 
    Cache
        BuildStream leverages various caching techniques in order to avoid
diff --git a/doc/source/using_commands.rst b/doc/source/using_commands.rst
index 27fe692..0ec39fc 100644
--- a/doc/source/using_commands.rst
+++ b/doc/source/using_commands.rst
@@ -77,6 +77,29 @@ Top-level commands
 Artifact subcommands
 --------------------
 
+
+.. _artifact_names:
+
+Artifact names
+~~~~~~~~~~~~~~
+Various artifact subcommands accept either :ref:`element names <format_element_names>`,
+which will operate on artifacts by deriving the artifact from local project state,
+or :term:`artifact names <Artifact name>` interchangeably as targets. Artifact names allow
+the user to operate directly on cached artifacts, without requiring local project data.
+
+An artifact name is composed of the following identifiers:
+
+* The :ref:`project name <project_format_name>`
+
+* The :ref:`element name <format_element_names>`, without any trailing ``.bst`` extension
+
+* The cache key of the element at the time it was built.
+
+To compose an artifact name, simply join these using a forward slash (``/``) charachter, like so: ``<project-name>/<element-name>/<cache-key>``.
+
+An artifact name might look like: ``project/target/788da21e7c1b5818b7e7b60f7eb75841057ff7e45d362cc223336c606fe47f27``
+
+
 .. _invoking_artifact_checkout:
 
 .. click:: buildstream._frontend.cli:artifact_checkout