[actions] cache the tox venvs

Author: stonier

.github/workflows/pre-merge.yaml

@@ -27,31 +27,31 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Poetry Cache Dir
+    - name: Poetry Venv Dir
       run: |
-        echo "POETRY_CACHE_DIR=$(poetry config virtualenvs.path)" >> $GITHUB_ENV
+        echo "VENV_DIR=$(poetry config virtualenvs.path)" >> $GITHUB_ENV
 
-    - name: Poetry Cache from Cache
+    - name: Restore the Cache
       id: cache-deps
       uses: actions/cache@v3
       with:
-        path: ${{ env.POETRY_CACHE_DIR }}
+        path: ${{ env.VENV_DIR }}
         # bump the suffix if you need to force-refresh the cache
-        key: poetry-cache-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}-1
+        key: py-trees-ci-cache-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock', '**/tox.ini') }}-1
 
     # Install all deps, sans the project (--no-root)
-    - name: Install Dependencies
+    - name: Poetry - Install Dependencies
       run: poetry install --no-interaction --no-root
       if: steps.cache-deps.outputs.cache-hit != 'true'
 
     # Project is installed separately to avoid always invalidating the cache
-    - name: Install Project
+    - name: Poetry - Install Project
       run: poetry install --no-interaction
 
     # TODO: Caching above doesn't make much sense when tox effectively re-installs deps
-    - name: Tests
-      run: poetry run tox -e ${{ matrix.python-py-version }}
-    - name: Formatters, Linters
-      run: poetry run tox -e check
-    - name: MyPy
-      run: poetry run tox -e my${{ matrix.python-py-version }}
+    - name: Tox - Tests
+      run: poetry run tox --workdir ${{ env.VENV_DIR }} -e ${{ matrix.python-py-version }}
+    - name: Tox - Formatters, Linters
+      run: poetry run tox --workdir ${{ env.VENV_DIR }} -e check
+    - name: Tox - MyPy
+      run: poetry run tox --workdir ${{ env.VENV_DIR }} -e my${{ matrix.python-py-version }}

.github/workflows/update-poetry-cache.yaml

@@ -1,9 +1,9 @@
 ################################################################################
-# Store a cache for dependencies on every merge to devel.
+# Ensure poetry and tox installed dependencies are in the cache.
 #
-# All PR's have access to devel's caches. This makes sure it gets generated and
-# is available for the next PR. Otherwise every PR will always generate a cache
-# for the first commit of the PR (subsequent commits will reuse that).
+# All PR's can reuse devel's caches, but a PR's cache cannot be reused from
+# one PR to the next. This jobs' sole purpose is to make sure every PR updates
+# devel's cache (if changes are needed) on merging.
 #
 # https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows
 ################################################################################
@@ -34,21 +34,25 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Poetry Cache Dir
+    - name: Poetry Venv Dir
       run: |
-        echo "POETRY_CACHE_DIR=$(poetry config virtualenvs.path)" >> $GITHUB_ENV
+        echo "VENV_DIR=$(poetry config virtualenvs.path)" >> $GITHUB_ENV
 
-    - name: Poetry Cache from Cache
+    - name: Restore the Cache
       id: cache-deps
       uses: actions/cache@v3
       with:
-        path: ${{ env.POETRY_CACHE_DIR }}
+        path: ${{ env.VENV_DIR }}
         # bump the suffix if you need to force-refresh the cache
-        key: poetry-cache-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}-1
+        key: py-trees-ci-cache-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock', '**/tox.ini') }}-1
 
     # Install all deps, sans the project (--no-root)
-    - name: Install Dependencies
+    - name: Poetry - Install Dependencies
       run: poetry install --no-interaction --no-root
       if: steps.cache-deps.outputs.cache-hit != 'true'
 
+    - name: Tox - Install Dependencies
+      run: poetry run tox --workdir ${{ env.VENV_DIR }} --notest -e ${{ matrix.python-py-version }} check my${{ matrix.python-py-version }}
+      if: steps.cache-deps.outputs.cache-hit != 'true'
+
 

README.md

@@ -14,12 +14,48 @@ PyTrees is a python implementation of behaviour trees designed to facilitate the
 * Python decorators for enabling meta behaviours
 * Render trees to dot graphs or visualise with ascii graphs on stdout
 
-## Docs and Demos
-
-Core API documentation (also includes some explanation concerning the demo scripts):
+## Documentation
 
 [![devel][docs-devel-image]][docs-devel] [![2.1.x][docs-2.1.x-image]][docs-2.1.x] [![0.7.x][docs-0.7.x-image]][docs-0.7.x] [![0.6.x][docs-0.6.x-image]][docs-0.6.x]
 
+## Getting Started
+
+VSCode and a [py38 DevContainer](.devcontainer/devcontainer.json) on CodeSpaces will set you up with an environment
+for running demos, tests and/or creating PRs in less than five minutes. If you're just looking for releases,
+fetch them from  [PyPi](https://pypi.org/project/py-trees/).
+
+1. Fork the project to your personal account
+2. Click on Code -> Codespaces -> + Create a Codespace
+3. Be froody
+
+```
+(docker) zen@py_trees:/workspaces/py_trees$ poetry install
+(docker) zen@py_trees:/workspaces/py_trees$ poetry shell
+
+(py-trees-py3.8) (docker) zen@py_trees:/workspaces/py_trees$ py-trees-demo-<tab>-<tab>
+py-trees-demo-action-behaviour            py-trees-demo-context-switching           py-trees-demo-logging
+py-trees-demo-behaviour-lifecycle         py-trees-demo-display-modes               py-trees-demo-pick-up-where-you-left-off
+py-trees-demo-blackboard                  py-trees-demo-dot-graphs                  py-trees-demo-selector
+py-trees-demo-blackboard-namespaces       py-trees-demo-either-or                   py-trees-demo-sequence
+py-trees-demo-blackboard-remappings       py-trees-demo-eternal-guard               py-trees-demo-tree-stewardship
+
+(py-trees-py3.8) (docker) zen@py_trees:/workspaces/py_trees$ py-trees-demo-blackboard
+*******************************************************************************
+                                   Blackboard
+*******************************************************************************
+
+Demonstrates usage of the blackboard and related behaviours.
+
+A sequence is populated with a few behaviours that exercise
+reading and writing on the Blackboard in interesting ways.
+
+*******************************************************************************
+
+[DEBUG] Writer               : BlackboardWriter.__init__()
+...
+...
+```
+
 If you're really looking for something more edifying than hello world examples, walk through the [ros tutorials](https://py-trees-ros-tutorials.readthedocs.io/en/release-2.0.x/index.html) which incrementally step through the process of building a scenario handling layer for a robot.
 
 There are also runtime visualisation tools - refer to the [py_trees_ros_viewer/README](https://github.com/splintered-reality/py_trees_ros_viewer/blob/devel/README.md) as an example implementation of the underlying [py_trees_js](https://github.com/splintered-reality/py_trees_js) library.