Merge branch 'jennis/frontend_documentation' into 'master'
Add UI section in CONTRIBUTING
See merge request BuildStream/buildstream!1584
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index b99ede4..048136e 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -264,3 +264,4 @@
hacking/grpc_protocols.rst
hacking/managing_data_files.rst
hacking/updating_python_deps.rst
+ hacking/ui.rst
diff --git a/doc/source/hacking/ui.rst b/doc/source/hacking/ui.rst
new file mode 100644
index 0000000..e37dda4
--- /dev/null
+++ b/doc/source/hacking/ui.rst
@@ -0,0 +1,78 @@
+Contributing to the UI
+~~~~~~~~~~~~~~~~~~~~~~
+
+As we wish to cleanly separate BuildStream's core from the frontend, anything
+user facing should be defined within the modules contained within the `_frontend
+<https://gitlab.com/BuildStream/buildstream/tree/master/src/buildstream/_frontend>`_
+directory.
+
+BuildStream's frontend includes:
+
+ * Implementation of the command line interface (cli.py)
+ * Logline/text formatting (widget.py)
+ * The main application state (app.py) which initializes the stream to handle
+ logging and user interactions.
+ * Colour profiles (profile.py)
+ * Rendering of the status bar (status.py)
+ * Autocompletion behaviour (completions.py)
+
+
+The command line interface
+''''''''''''''''''''''''''
+
+All of BuildStream's commands are defined within the module `cli.py
+<https://gitlab.com/BuildStream/buildstream/blob/master/src/buildstream/_frontend/cli.py>`_ -,
+the main entry point which implements the CLI.
+
+The command line interface is generated with `Click
+<https://palletsprojects.com/p/click/>`_ - a third party Python package. Click
+is easy to use and automatically generates help pages.
+
+When working with commands, please adhere to the following checklist:
+
+1. All commands should be defined with a help text
+2. The command should be placed within the appropriate sub group
+
+ - If the command manipulates sources, it should be part of the
+ :ref:`source_subcommands`.
+ - If the command manipulates cached artifacts, it should be part of the
+ :ref:`artifact_subcommands`.
+ - If the command has anything to do with workspaces, it should be part
+ of the :ref:`workspace_subcommands`.
+
+3. If the command is intended to work with artifact refs as well as element
+ names, the command's argument should be "artifacts" as this supports the
+ auto-completion of artifact refs.
+4. The supported `--deps` options are: "run", "build", "all", "plan" and "none".
+ These are always of type `click.Choice
+ <https://click.palletsprojects.com/en/7.x/options/#choice-options>`_ and
+ should always be specified with a default. If the default is "none", note that
+ we use the string "none", not the Python built-in ``None``. In addition to this,
+ the ``show_default`` flag should be set to ``True``.
+5. Commands should use the app and go through the stream (via a similarly named
+ method within Stream) in order to communicate to BuildStream's core.
+
+
+Displaying information
+''''''''''''''''''''''
+
+Output which we wish to display to the user from the frontend should use the
+implemented classes in widget.py. This module contains classes which represent
+widgets for displaying information to the user.
+
+To report messages back to the frontend, we use the ``Message()`` object
+which is available from the ``Context``.
+
+Supported message types are defined in `_message.py
+<https://gitlab.com/BuildStream/buildstream/blob/master/src/buildstream/_message.py>`_
+and various uses of the messenger are defined in `_messenger.py
+<https://gitlab.com/BuildStream/buildstream/blob/master/src/buildstream/_messenger.py>`_
+
+The ``Messenger`` class defines various methods which allow us to report back to
+the frontend in particular ways. The common methods are:
+
+* ``Messenger.message()`` - the central point through which all messages pass
+* ``Messenger.timed_activity()`` - a context manager for performing and logging
+ timed activities.
+* ``Messenger.simple_task()`` - a Context manager for creating a task to report
+ progress too.
diff --git a/doc/source/using_commands.rst b/doc/source/using_commands.rst
index 53c3619..276a17c 100644
--- a/doc/source/using_commands.rst
+++ b/doc/source/using_commands.rst
@@ -72,6 +72,8 @@
:prog: bst workspace
+.. _artifact_subcommands:
+
Artifact subcommands
--------------------
@@ -108,6 +110,22 @@
.. click:: buildstream._frontend.cli:artifact_delete
:prog: bst artifact delete
+----
+
+.. _invoking_artifact_show:
+
+.. click:: buildstream._frontend.cli:artifact_show
+ :prog: bst artifact show
+
+----
+
+.. _invoking_artifact_list_contents:
+
+.. click:: buildstream._frontend.cli:artifact_list_contents
+ :prog: bst artifact list-contents
+
+
+.. _source_subcommands:
Source subcommands
------------------
@@ -132,6 +150,8 @@
:prog: bst source checkout
+.. _workspace_subcommands:
+
Workspace subcommands
---------------------
