update readme and names, add tests, add github actino for pip install test

Author: Nathan Hammond

.github/workflows/docker-build.yml …workflows/docker-build-test-and-push.yml.github/workflows/docker-build.yml renamed to .github/workflows/docker-build-test-and-push.yml .github/workflows/docker-build.yml renamed to .github/workflows/docker-build-test-and-push.yml

@@ -0,0 +1,33 @@
+name: Test pip install
+
+on:
+  push:
+    branches:
+      - "*"
+  pull_request:
+    branches:
+      - "*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+
+    - name: Install package
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install .
+
+    - name: Test with unittest
+      run: |
+        python -m unittest discover

.github/workflows/test-pip-install.yml

@@ -1,3 +1,6 @@
+# For setuptools-scm automatic versioning, do not check in auto-generated _version.py file
+_version.py
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.gitignore

@@ -45,4 +45,6 @@ RUN echo "REF_NAME: $REF_NAME"
 RUN pip install --upgrade pip setuptools && \
     pip install /src/${PROJECT}
 
-ENTRYPOINT ["python3", "-m", "napari"]
+RUN python3 -m unittest discover
+
+ENTRYPOINT ["python3", "-m", "napari"]

Dockerfile

@@ -15,18 +15,66 @@ conda env create --file compmicro-ndutils-env/environment.yml
 ```
 
 ### Docker
+A docker image is automatically built using GitHub actions whenever a version tag is pushed. See the GitHub-hosted [compmicro-ndutils-env](https://github.com/czbiohub-sf/compmicro-ndutils-env/pkgs/container/compmicro-ndutils-env) Docker repository.
+
+To pull and run a Docker image:
+```
+docker run ghcr.io/czbiohub-sf/compmicro-ndutils-env:${VERSION}
+```
+
+To build a Docker image manually:
 ```
 git clone [email protected]:czbiohub-sf/compmicro-ndutils-env.git
 cd compmicro-ndutils-env
 docker build .
 ```
 
+## Apptainer
+To run an Apptainer container created from the Docker image:
+```
+apptainer run docker://ghcr.io/czbiohub-sf/compmicro-ndutils-env:${VERSION}
+```
+
+Or to run a bash shell in Apptainer:
+```
+apptainer exec docker://ghcr.io/czbiohub-sf/compmicro-ndutils-env:${VERSION} bash
+```
+
 ## Checking the installed version
-You can check the version of the installed ndutils environment using the ndutils_version command or with "pip list"
+You can check the version of the installed ndutils environment using the env_version command or with "pip list" or "pip show".
+
 ```
-$ ndutils_version
-0.2.0.dev2
+$ env_version
+ndutils 0.2.0.dev3
 
 $ pip list | grep ndutils
-compmicro-ndutils-env         0.2.0.dev2
+ndutils         0.2.0.dev3
+
+$ pip show ndutils
+Name: ndutils
+Version: 0.2.0.dev3
+Summary: ndutils compute environment for computational microscopy at CZBiohub SF
+...
 ```
+
+## Creating a new release
+To update this environment:
+* Check out the git repo and make edits
+  * Update Python dependencies by editing requirements.txt (which is used by Conda, Docker, and Pip install methods)
+  * Update Python version by editing both environment.yml (for Conda) and Dockerfile
+* Commit and push/merge changes to the *main* branch
+* Tag the commit with a version identifier (`git tag x.y.z`)
+* Push the tag with `git push --tags` (warning this pushes ALL local tags)
+* Monitor [GitHub actions](https://github.com/czbiohub-sf/compmicro-ndutils-env/actions) to confirm the build succeeds
+* If needed, deploy the new environment to your infrastructure (e.g. by running "conda update ...".) Deployment documentation is not included here as it varies between sites.
+
+## Creating a new environment
+If you want to use the code in this repo as a template for creating a new environment, you will need to make the following changes:
+* Create a new repo in GitHub. (Defining multiple environments in one GitHub repo is to be avoided because it complicates versioning and automatically building each environment separately.)
+* When copying files into the new repo, be sure to include the hidden ".github/" directory and ".gitignore" file, but exclude the ".git/" directory. (A fresh ".git" directory will be creating either by `git init` or by cloning a clean repo created in GitHub.)
+* Edit the following files and directories to update references to the git repo name (compmicro-ndutils-env), Python package name and conda environment name (ndutils), environment name. (You may want to grep to make sure there are not any others.)
+  * README.md
+  * pyproject.toml
+  * ndutils/
+* Edit the Dockerfile to ensure an appropriate ENTRYPOINT is used, if any, for the new environment.
+* Commit, tag, and push the updated code as described in "Creating a new release".

README.md

@@ -1,6 +1,14 @@
 from . import _version
 
+
 # The "_version.py" file is generated by setuptools_scm on installation
 
-def version():
-    print(f"{__name__}: {_version.version}")
+
+def env_version():
+    package, version = _env_version_tuple()
+    print(f"{package}\t{version}")
+
+
+def _env_version_tuple():
+    package = __name__
+    return (package, _version.version)

ndutils/.gitignore

@@ -0,0 +1,22 @@
+from unittest import TestCase
+from unittest.mock import patch
+from io import StringIO
+
+from . import env_version, _env_version_tuple
+
+
+class TestEnvVersion(TestCase):
+
+    @patch('sys.stdout', new_callable=StringIO)
+    def test_env_version(self, mock_stdout):
+        # Confirm non-empty stdout when calling env_version
+        # Excpected value is "${package_name}\t${version}"
+        env_version()
+        self.assertTrue(len(mock_stdout.getvalue()) > 0)
+
+    def test_env_version_tuple(self):
+        # Confirm non-empty strings for package and version
+        (package, version) = _env_version_tuple()
+        self.assertTrue(len(package) > 0)
+        self.assertTrue(len(version) > 0)
+

ndutils/__init__.py

@@ -28,7 +28,7 @@ classifiers = [
 ]
 
 [project.scripts]
-ndutils_version = "ndutils:version"
+env_version = "ndutils:env_version"
 
 [project.urls]
 "Homepage" = "https://github.com/czbiohub-sf/compmicro-ndutils-env"