docs: More documentation.

Add commands and runtimes section, and add more use case examples to the
quick-start section.

Signed-off-by: Ryan Roberts <ryan.roberts@arm.com>

4 files changed, 154 insertions, 2 deletions

diff --git a/documentation/conf.py b/documentation/conf.py
index 5c57195..51bda80 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -38,6 +38,7 @@ extensions = [
     'sphinx.ext.autosectionlabel',
     'sphinx_rtd_theme',
     'sphinx_copybutton',
+    'sphinx.ext.todo',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -83,6 +84,9 @@ html_theme_options = {
 
 # -- Extension configuration -------------------------------------------------
 
+# Display todos by setting to True
+todo_include_todos = True
+
 # -- Options for autosectionlabel --------------------------------------------
 
 # Prefix each section label with the name of the document it is in
diff --git a/documentation/user_guide/commands.rst b/documentation/user_guide/commands.rst
index a2db52e..2600007 100644
--- a/documentation/user_guide/commands.rst
+++ b/documentation/user_guide/commands.rst
@@ -6,3 +6,25 @@
 ########
 Commands
 ########
+
+For documentation on the commands that shrinkwrap supports, add ``--help`` to
+the command line.
+
+For top-level help:
+
+.. code-block:: shell
+
+  shrinkwrap --help
+
+For help on a specific command:
+
+.. code-block:: shell
+
+  shrinkwrap inspect --help
+  shrinkwrap build --help
+  shrinkwrap run --help
+  shrinkwrap process --help
+
+.. todo::
+
+  Automate importing the help pages into this documentation.
diff --git a/documentation/user_guide/quickstart.rst b/documentation/user_guide/quickstart.rst
index 64df583..073f4e8 100644
--- a/documentation/user_guide/quickstart.rst
+++ b/documentation/user_guide/quickstart.rst
@@ -7,7 +7,11 @@ Install Shrinkwrap
 ******************
 
 Packages don't yet exist, so currently the only way to install Shrinkwrap is to
-install its dependencies and clone the git repository:
+install its dependencies and clone the git repository.
+
+Shrinkwrap requires at least Python 3.7 (for ordered dicts). If using a version
+older than 3.9, you will also need to install the ``graphlib-backport`` pip
+package.
 
 .. code-block:: shell
 
@@ -189,7 +193,7 @@ provide a value when running the config.
   </p>
 
 Now build the ``ns-preload.yaml`` config. This is the simplest config that
-allows booking a kernel on FVP. (optionally add ``--verbose`` to see all the
+allows booting a kernel on FVP. (optionally add ``--verbose`` to see all the
 output from the component build systems).
 
 .. code-block:: shell
@@ -360,3 +364,91 @@ forwards stdin to the ``tfa+linux`` uart terminal:
 
   </details>
   </p>
+
+************************************
+Use Case: Override Component Version
+************************************
+
+You can change many, many configuration options by overlaying a config on top of
+an existing config. Here we modify the revision of the TF-A component from the
+``master`` branch (the default defined in tfa-base.yaml), to the ``v2.7.0`` tag.
+You could also specify the revision as a SHA or override the remote repo URL,
+etc.
+
+We will use the ``ns-edk2-dt.yaml`` config to spice things up a bit. This loads
+EDK2 on top of TF-A then EDK2 pulls the kernel, dtb and command line from the
+host system using semihosting.
+
+.. warning::
+
+  If you have previously built this config, shrinkwrap will skip syncing the git
+  repos since they will already exist and it doesn't want to trample any user
+  changes. So you will need to force shrinkwrap to re-sync. One approach is to
+  delete the following directories:
+
+  - ``<SHRINKWRAP_BUILD>/source/ns-edk2-dt``
+  - ``<SHRINKWRAP_BUILD>/build/ns-edk2-dt``
+
+Create a file called ``my-overlay.yaml``:
+
+.. code-block:: yaml
+
+  build:
+    tfa:
+      repo:
+        revision: v2.7.0
+
+Optionally, you can view the final, merged config as follows:
+
+.. code-block:: shell
+
+  shrinkwrap --runtime=docker process --action=merge --overlay=my-overlay.yaml ns-edk2-dt.yaml
+
+Now do a build, passing in the overlay:
+
+.. code-block:: shell
+
+  shrinkwrap --runtime=docker build --overlay=my-overlay.yaml ns-edk2-dt.yaml
+
+Finally, boot the config. Here, were are providing a custom kernel command line.
+But you could omit this and a sensible default would be used. Note that because
+EDK2 outputs ncurses-like output, this config starts the appropriate terminal in
+telnet mode and provides the command that you need to enter in a separate
+window. Follow the instructions, then in EDK2, navigate to Boot Manager -> UEFI
+Shell. This will cause the kernel to boot:
+
+.. code-block:: shell
+
+  shrinkwrap --runtime=docker run --rtvar=KERNEL=path/to/Image --rtvar=ROOTFS=path/to/rootfs.img --rtvar="CMDLINE=console=ttyAMA0 earlycon=pl011,0x1c090000 root=/dev/vda ip=dhcp" ns-edk2-dt.yaml
+
+***********************************
+Use Case: Reuse Existing Local Repo
+***********************************
+
+By default, shrinkwrap will sync the git repos for all required components to a
+private location the first time you build a given config. However, sometimes you
+want shrinkwrap to reuse a repo that already exists on your local system. In
+this case, Shrinkwrap will build this source into its own private build tree,
+leaving the source tree unmodified.
+
+.. warning::
+
+  Components support building in a tree separate from the source to differing
+  degrees. For example, TF-A will always build fiptool in the source tree,
+  although it will build all the FW components in the correct build tree. So
+  depending on the component you are sharing source for, you may see some build
+  artifacts appear.
+
+Create a file called ``my-overlay.yaml``:
+
+.. code-block:: yaml
+
+  build:
+    tfa:
+      sourcedir: /path/to/my/tfa/git/repo
+
+Now do a build, passing in the overlay:
+
+.. code-block:: shell
+
+  shrinkwrap --runtime=docker build --overlay=my-overlay.yaml ns-edk2-dt.yaml
diff --git a/documentation/user_guide/runtimes.rst b/documentation/user_guide/runtimes.rst
index fb994f2..f5f4793 100644
--- a/documentation/user_guide/runtimes.rst
+++ b/documentation/user_guide/runtimes.rst
@@ -7,6 +7,40 @@
 Run-Times
 #########
 
+Shrinkwrap uses a "runtime" to execute all of its shell commands and allows the
+user to choose which runtime to use. Both the design and implementation of this
+is borrowed from `Tuxmake <https://tuxmake.org>`_.
+
+Shrinkwrap supports the following set of runtimes:
+
+============ ====
+runtime      description
+============ ====
+null         (default). Shell commands are executed natively on the user's system. The user is responsible for ensuring the the required toolchain, environment variables and any other dependencies are set up.
+docker       Shell commands are executed in a docker container. By default, the official shrinkwrap image will be pulled and used, which contains all dependencies already setup.
+docker-local Like docker, but will only look for the container image on the local system. Will not attempt to pull over the network.
+podman       Like docker, but runs the container using podman.
+podman-local Like docker-local, but runs the container using podman.
+============ ====
+
+.. warning::
+
+  ``podman`` and ``podman-local`` are not well-tested, and are probably broken.
+
+The desired runtime can be specified using the ``--runtime`` option, which is a
+top-level argument (must come before the command):
+
+.. code-block:: shell
+
+  shrinkwrap --runtime=<name> ...
+
+If using a container runtime (anything other than null), a custom image can
+optionally be specified. If omitted, the official shrinkwrap image is used:
+
+.. code-block:: shell
+
+  shrinkwrap --runtime=<name> --image=<name> ...
+
 ***********************************
 Log into Arm Artifactory Repository
 ***********************************