Merge pull request #8 from olcf/feature/rework

Feature/rework

.github/workflows/python-publish.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -9,3 +9,5 @@
 ############################################################
 tmp
 *__pycache__
+dist
+*\.egg-info

README.md

@@ -1,7 +1,7 @@
-<h1><img align="center" height="50" src="assets/artwork/icon.drawio.png"> VELOCITY</h1>
+<h1><img align="center" height="50" src="misc/artwork/icon.drawio.png"> VELOCITY</h1>
 
 ## Description
-Container build system.
+A container build manager.
 
 ## Documentation
 Run:
@@ -12,4 +12,7 @@ python3 -m http.server 8080
 And then go to <http://localhost:8080>.
 
 ## Installation
-Simply run the `setup-env.sh` script and set the correct variables.
+``` commandline
+pip install olcf-velocity
+alias velocity="python3 -m velocity"
+```

docs/build/html/_sources/index.rst.txt

@@ -4,8 +4,10 @@
    contain the root `toctree` directive.
 
 
-Velocity Container Build System
-===============================
+Velocity Container Build Management
+===================================
+Velocity is a tool to help with the maintenance of container build scripts on multiple systems, backends
+(e.g podman or apptainer) and distros.
 
 .. toctree::
    :maxdepth: 2

docs/build/html/_sources/reference/build.rst.txt

@@ -6,16 +6,14 @@ This page describes the steps that velocity goes through when building an image.
 
 Setup
 #####
-After selecting images to build and ordering them. Velocity will start by assigning a random
-id to each image to be built. It will also create a directory BSD (Build Sub Dir) named with that random id in
-`VELOCITY_BUILD_DIR`.
+After selecting images to build and ordering them Velocity will also create a directory BSD (Build Sub Dir)
+named ``<name>-<version>-<hash>`` in build directory.
 
 .. _files:
 
 Files
 #####
-Next Velocity will look for a folder in the image definition directory with the same name as `VELOCITY_SYSTEM`. All
-of the files in this directory will be copied to the BSD.
+Next Velocity will copy any files that you specified.
 
 Parse Template
 ##############
@@ -32,18 +30,20 @@ Finally velocity will run the `build` script and log the output to a file called
 
 Build Directory Layout
 ######################
-At the end of a build `VELOCITY_BUILD_DIR` should look somthing like this. With the addition of any other files that
+At the end of a build the build dir should look somthing like this. With the addition of any other files that
 got copied in the :ref:`files<files>` step.
 
 .. code-block:: bash
 
     .
-    ├── jknqsnkc
-    │   ├── build
-    │   ├── log
-    │   └── script
-    └── nfhmhmsh
+    ├── fedora-41-8a9a360
+    │ ├── 8a9a360.sif
+    │ ├── build
+    │ ├── log
+    │ └── script
+    └── hello-world-1.0-de9c02b
         ├── build
+        ├── de9c02b.sif
+        ├── hello_world.py
         ├── log
         └── script
-

docs/build/html/_sources/reference/config.rst.txt

@@ -0,0 +1,64 @@
+*************
+Configuration
+*************
+
+Configuration for Velocity comes from three places. Command line options, environment variables and the configuration file.
+
+Commandline Options
+###################
+These take the highest level of precedence and can be viewed by using the ``--help`` option in the command line.
+
+Variables
+#########
+Variables are the second highest level of configuration.
+
+`VELOCITY_IMAGE_PATH`
+---------------------
+
+This variable points to the directories containing the the image definitions.
+
+`VELOCITY_SYSTEM`
+-----------------
+This variable specifies what computer system you are building for (e.g. frontier).
+
+`VELOCITY_BACKEND`
+------------------
+This variable specifies the container backend that should be used (e.g podman).
+
+`VELOCITY_DISTRO`
+-----------------
+This variable specifies the distro of the container images that will be built. This name is flexable and completely
+up to the user. It is used purely for organizational purposes.
+
+`VELOCITY_BUILD_DIR`
+--------------------
+This variable specifies a scratch space for Velocity to preform builds in.
+
+`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.
+
+.. code-block:: yaml
+
+    velocity:
+      system: frontier
+      backend: apptainer
+      distro: ubuntu
+      debug: INFO   # set the debug level
+      image_path:   # a list of : seperated paths
+      build_dir:    # path to a scratch space
+
+Additionally you can set :ref:`arguments` and :ref:`specVariables` at a global level in the constraints section. As an example here
+we are adding ``--disable-cache`` as an argument for every image build we do with apptainer.
+
+.. code-block:: yaml
+
+    constraints:
+      arguments:
+        - value: --disable-cache
+          when: backend=apptainer

docs/build/html/_sources/reference/index.rst.txt

@@ -8,6 +8,7 @@ Technical Docs
 .. toctree::
    :maxdepth: 2
 
+   config
    vtmp
-   specifications
+   specs
    build