Update docs before 0.2 release

.github/workflows/documentation.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install sphinx sphinx-rtd-theme
+          pip install sphinx sphinx-rtd-theme sphinx-copybutton
       - name: Build Docs
         run: |
           cd docs && make html

docs/source/conf.py

@@ -15,11 +15,15 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = [
+    'sphinx_copybutton'
+]
 
 templates_path = ['_templates']
 exclude_patterns = []
 
+# copybutton configuration
+copybutton_prompt_text = "$ "
 
 
 # -- Options for HTML output -------------------------------------------------

docs/source/reference/config.rst

@@ -12,6 +12,8 @@ Variables
 #########
 Variables are the second highest level of configuration.
 
+.. _velocity_image_path:
+
 `VELOCITY_IMAGE_PATH`
 ---------------------
 
@@ -25,6 +27,10 @@ This variable specifies what computer system you are building for (e.g. frontier
 ------------------
 This variable specifies the container backend that should be used (e.g podman).
 
+.. important::
+
+    Available backends are ``apptainer``, ``docker``, ``podman`` and ``singularity``.
+
 `VELOCITY_DISTRO`
 -----------------
 This variable specifies the distro of the container images that will be built. This name is flexable and completely
@@ -36,14 +42,17 @@ up to the user. It is used purely for organizational purposes.
 --------------------
 This variable specifies a scratch space for Velocity to preform builds in.
 
+.. _velocity_config_dir:
+
 `VELOCITY_CONFIG_DIR`
 ---------------------
+
 This variable specifies where to look for the configuration file.
 
 Configuration File
 ##################
 The configuration file is the lowest level of configuration. By default Velocity looks for ``config.yaml`` in
-``~/.velocity`` unless ``VELOCITY_CONFIG_DIR`` is set. A number of configuration option for velocity can be set.
+``~/.velocity`` unless :ref:`velocity_config_dir` is set. A number of configuration option for velocity can be set.
 
 .. code-block:: yaml
 
@@ -64,3 +73,8 @@ we are adding ``--disable-cache`` as an argument for every image build we do wit
       arguments:
         - value: --disable-cache
           when: backend=apptainer
+
+.. note::
+
+    Arguments and variables can also be set from the command line when building by passing something like
+    ``-A "value: --disable-cache; when: backend=apptainer"`` to the build command for as many arguments as needed.

docs/source/reference/vtmp.rst

@@ -100,6 +100,10 @@ Sections
 The `@from` section is used to specify the base image to build on top of. Both Podman and Apptainer support pulling
 from docker registries. Apptainer also supports building from a sif file. The `@from` section can only have one line in it.
 
+.. note::
+
+    The Apptainer backend supports oras images as well. Simply use the ``oras://<image_url>`` format.
+
 .. _pre_section:
 
 @pre

docs/source/starting/setup.rst

@@ -21,7 +21,7 @@ Velocity works by building a set of containers in a chain so that the final cont
 .. important::
 
     Velocity maintains a very hands off approach. It is only as good as the templates/configuration that you write.
-    In general it will assume that a particular build will work unless you tell it otherwise.
+    In general it will assume that a particular build will work (on a system, distro etc.) unless you tell it otherwise.
 
 .. note::
 
@@ -35,6 +35,7 @@ The easiest way to install velocity is to install prebuilt python packages using
 
 .. code-block:: bash
 
+    # note: you will need python 3.10 or greater
     pip install olcf-velocity
 
 Alternatively, you can clone the velocity repository and build/install velocity from source.

docs/source/starting/tutorial.rst

@@ -223,10 +223,10 @@ OLCF Images
 Let's extend what we have done so far and explore some more features of Velocity using a base set of image definitions
 provided at https://github.com/olcf/velocity-images. Clone the repository and run:
 
-.. warning::
+.. note::
 
-    You will need to delete the ``opensuse`` image that you made or it will conflict with the OLCF image; however,
-    leave your ``hello-world`` image because we will use it.
+    The ``opensuse`` image in the git repository will override the ``opensuse`` image you just created because velocity
+    selects conflicting images by their order in :ref:`velocity_image_path`.
 
 .. code-block:: bash
 

docs/source/starting/usage.rst

@@ -33,14 +33,20 @@ The `avail` command prints the defined images that can be built.
         6.0.1
         6.1.3
 
+    $ velocity avail gcc
+    ==> gcc
+        12.3.0
+        13.2.0
+        14.1.0
+
 Each image is listed and then indented underneath is a list of the available versions.
 
 `spec`
 ------
 
 The `spec` command shows the dependencies for a given image (or list of images) in a tree like structure.
 
-.. code-block:: bash
+.. code-block:: text
 
     $ velocity spec rocm
       > [email protected]
@@ -51,7 +57,7 @@ The `spec` command shows the dependencies for a given image (or list of images)
 
 The `build` command can be used to build an container image from one or more image definitions.
 
-.. code-block:: bash
+.. code-block:: text
 
     $ velocity build opensuse
     ==> Build Order:
@@ -66,7 +72,7 @@ The `build` command can be used to build an container image from one or more ima
 
 Both the spec and the build command can also take a list of images.
 
-.. code-block:: bash
+.. code-block:: text
 
     $ velocity build opensuse mpich
     ==> Build Order:

misc/vim/vtmp.vim

@@ -1,8 +1,8 @@
 " Vim syntax file
 " Language: Velocity Template
 " Maintainer: Asa Rentschler
-" Latest Revision: September, 19, 2024
-" Velocity Version: 0.1
+" Latest Revision: November, 15, 2024
+" Velocity Version: 0.2
 " Place this file in ~/.vim/syntax/ and add `au BufRead,BufNewFile *.vtmp set filetype=vtmp` to ~/.vimrc
 
 if exists("b:current_syntax")
@@ -13,7 +13,8 @@ endif
 syn match codeComment '>>>.*'
 
 " velocity variables
-syn keyword velocityVariable __backend__ __base__ __distro__ __name__ __system__ __version__ __timestamp__
+syn keyword velocityVariable __arch__ __backend__ __base__ __distro__ __name__ __threads__ __timestamp__ __system__
+syn keyword velocityVariable __version__ __version_major__ __version_minor__ _version_patch__ __version_suffix__
 
 " velocity operatives
 syn match velocityOperative '|'
@@ -40,10 +41,12 @@ syn region conditionalRegion matchgroup=velocityOperative start="??" end="??" co
 
 let b:current_syntax = "vtmp"
 
+setlocal tabstop=4 expandtab
+
 hi def link codeComment Comment
 hi def link sectionHeader Function
-hi def link velocityOperative Operator
+hi def link velocityOperative PreProc
 hi def link velocityVariable Identifier
 hi def link templateVariable Identifier
 hi def link argumentName Identifier
-hi def link conditionalArrow Operator
+hi def link conditionalArrow PreProc