From ff67239704fdfe582a81f9f9e8e3e13398fea274 Mon Sep 17 00:00:00 2001 From: Asa Rentschler Date: Fri, 15 Nov 2024 14:24:23 -0500 Subject: [PATCH] Update docs before 0.2 release --- .github/workflows/documentation.yml | 2 +- docs/source/conf.py | 6 ++- docs/source/reference/config.rst | 16 +++++- docs/source/reference/vtmp.rst | 4 ++ docs/source/starting/setup.rst | 3 +- docs/source/starting/tutorial.rst | 6 +-- docs/source/starting/usage.rst | 12 +++-- misc/scripts/setup-env.sh | 84 ----------------------------- misc/vim/vtmp.vim | 13 +++-- 9 files changed, 47 insertions(+), 99 deletions(-) delete mode 100755 misc/scripts/setup-env.sh diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 2ba3039..f4b541d 100644 --- a/.github/workflows/documentation.yml +++ b/.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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 5cbc35c..6cc3db4 100644 --- a/docs/source/conf.py +++ b/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 ------------------------------------------------- diff --git a/docs/source/reference/config.rst b/docs/source/reference/config.rst index b46b976..c56223c 100644 --- a/docs/source/reference/config.rst +++ b/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. \ No newline at end of file diff --git a/docs/source/reference/vtmp.rst b/docs/source/reference/vtmp.rst index 2c05c5a..6bfb657 100644 --- a/docs/source/reference/vtmp.rst +++ b/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://`` format. + .. _pre_section: @pre diff --git a/docs/source/starting/setup.rst b/docs/source/starting/setup.rst index ee8b0ab..688bfd9 100644 --- a/docs/source/starting/setup.rst +++ b/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. diff --git a/docs/source/starting/tutorial.rst b/docs/source/starting/tutorial.rst index 38c6c8f..fd4b64c 100644 --- a/docs/source/starting/tutorial.rst +++ b/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 diff --git a/docs/source/starting/usage.rst b/docs/source/starting/usage.rst index a5d9f5b..45e3a63 100644 --- a/docs/source/starting/usage.rst +++ b/docs/source/starting/usage.rst @@ -33,6 +33,12 @@ 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` @@ -40,7 +46,7 @@ Each image is listed and then indented underneath is a list of the available ver 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 > rocm@6.1.3-2a35af4 @@ -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: diff --git a/misc/scripts/setup-env.sh b/misc/scripts/setup-env.sh deleted file mode 100755 index 2bb0a4e..0000000 --- a/misc/scripts/setup-env.sh +++ /dev/null @@ -1,84 +0,0 @@ -#!/usr/bin/env bash - -# VELOCITY_ROOT (& PATH) -echo -VELOCITY_ROOT="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" -echo "VELOCITY_ROOT=$VELOCITY_ROOT" -export VELOCITY_ROOT -export PATH=$VELOCITY_ROOT:$PATH - -# VELOCITY_IMAGE_DIR -echo -read -rp "Set VELOCITY_IMAGE_DIR [$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )-images]: " VELOCITY_IMAGE_DIR -if [[ -z $VELOCITY_IMAGE_DIR ]]; then - VELOCITY_IMAGE_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )-images" -fi -echo "VELOCITY_IMAGE_DIR=$VELOCITY_IMAGE_DIR" -export VELOCITY_IMAGE_DIR - - -# VELOCITY_SYSTEM -echo -old_ifs=$IFS -IFS='.' -read -ra split_hostname <<< "$(hostname -f)" -IFS=$old_ifs -read -rp "Set VELOCITY_SYSTEM [${split_hostname[1]}]: " VELOCITY_SYSTEM -if [[ -z $VELOCITY_SYSTEM ]]; then - VELOCITY_SYSTEM=${split_hostname[1]} -fi -echo "VELOCITY_SYSTEM=$VELOCITY_SYSTEM" -export VELOCITY_SYSTEM - -# VELOCITY_BACKEND -echo -echo "Select VELOCITY_BACKEND: " -select VELOCITY_BACKEND in podman apptainer; do - case $VELOCITY_BACKEND in - podman) - break - ;; - apptainer) - break - ;; - *) - continue - ;; - esac -done -echo "VELOCITY_BACKEND=$VELOCITY_BACKEND" -export VELOCITY_BACKEND - -# VELOCITY_DISTRO -echo -echo "Select VELOCITY_DISTRO: " -select VELOCITY_DISTRO in centos ubuntu opensuse fedora; do - case $VELOCITY_DISTRO in - centos) - break - ;; - ubuntu) - break - ;; - opensuse) - break - ;; - fedora) - break - ;; - *) - continue - ;; - esac -done -echo "VELOCITY_DISTRO=$VELOCITY_DISTRO" -export VELOCITY_DISTRO - -# VELOCITY_BUILD_DIR -echo -read -rp "Set VELOCITY_BUILD_DIR [/tmp/velocity/build]: " VELOCITY_BUILD_DIR -if [[ -z $VELOCITY_BUILD_DIR ]]; then - VELOCITY_BUILD_DIR="/tmp/velocity/build" -fi -echo "VELOCITY_BUILD_DIR=$VELOCITY_BUILD_DIR" -export VELOCITY_BUILD_DIR diff --git a/misc/vim/vtmp.vim b/misc/vim/vtmp.vim index 4d861f8..0192013 100644 --- a/misc/vim/vtmp.vim +++ b/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 \ No newline at end of file +hi def link conditionalArrow PreProc