doc: develop: west: Add alias documentation

Add documentation and examples for west aliases.

Signed-off-by: Pieter De Gendt <[email protected]>

Author: pdgendt

doc/develop/west/alias.rst

@@ -0,0 +1,61 @@
+.. _west-aliases:
+
+West aliases
+############
+
+West allows to add alias commands to the local, global or system configuration files.
+These aliases make it easy to add shortcuts for frequently used, or hard to memorize
+commands for ease of development.
+
+Similar to how ``git`` aliases work, the alias command is replaced with the alias'
+full text and parsed as a new shell argument list (using the Python function
+`shlex.split()`_ internally to split the value). This enables adding argument
+parameters as they were passed to the original command. Spaces are considered
+argument separators; use proper escaping if arguments shouldn't be split.
+
+.. _shlex.split(): https://docs.python.org/3/library/shlex.html#shlex.split
+
+To add a new alias simply call the ``west config`` command:
+
+.. code-block:: shell
+
+   west config alias.mylist "list -f '{name} {revision}'"
+
+To list aliases, use :samp:`west help {some_alias}`.
+
+Recursive aliases are allowed as an alias command can contain other aliases, effectively
+building more complex but easy-to-remember commands.
+
+It is possible to override an existing command, for example to pass default arguments:
+
+.. code-block:: shell
+
+   west config alias.update "update -o=--depth=1 -n"
+
+.. warning::
+
+   Overriding/shadowing other or built-in commands is an advanced use case, it can lead to
+   strange side-effects and should be done with great care.
+
+Examples
+--------
+
+Add ``west run`` and ``west menuconfig`` shortcuts to your global configuration to
+call ``west build`` with the corresponding CMake targets:
+
+.. code-block:: shell
+
+   west config --global alias.run "build --pristine=never --target run"
+   west config --global alias.menuconfig "build --pristine=never --target menuconfig"
+
+Create an alias for the sample you are actively developing with additional options:
+
+.. code-block:: shell
+
+   west config alias.sample "build -b native_sim samples/hello_world -t run -- -DCONFIG_ASSERT=y"
+
+Override ``west update`` to check a local cache:
+
+.. code-block:: shell
+
+   west config alias.update "update --path-cache $HOME/.cache/zephyrproject"

doc/develop/west/config.rst

@@ -130,6 +130,9 @@ commands are documented in the pages for those commands.
 
    * - Option
      - Description
+   * - :samp:`alias.{ALIAS}`
+     - String. If non-empty the ``<ALIAS>`` can be used as a west command.
+       See :ref:`west-aliases`.
    * - ``color.ui``
      - Boolean. If ``true`` (the default), then west output is colorized when
        stdout is a terminal.

doc/develop/west/index.rst

@@ -37,6 +37,7 @@ each command.
    workspaces.rst
    manifest.rst
    config.rst
+   alias.rst
    extensions.rst
    build-flash-debug.rst
    sign.rst