Documentation improvements, make PyPI and Docker builds respect versi…

…on control, and release for Version 0.1.17

.github/workflows/docker-publish.yaml

@@ -54,7 +54,8 @@ jobs:
       - name: Tagged Docker Hub
         if: ${{ github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v') }}
         run: |
-          echo "IMAGE_TAG=latest" >> $GITHUB_ENV
+          VERSION=$(echo ${GITHUB_REF} | sed 's#.*/v##')
+          echo "IMAGE_TAG=${VERSION}" >> $GITHUB_ENV
 
       # Push bleeding-edge image (main tag) to registries
       - name: Bleeding Edge Docker Hub
@@ -73,6 +74,15 @@ jobs:
         run: |
           docker buildx build \
               -t wildme/scoutbot:${{ env.IMAGE_TAG }} \
+              --platform linux/amd64 \
+              --push \
+              .
+
+      # Also push latest image
+      - name: Build Codex
+        if: ${{ github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v') }}
+        run: |
+          docker buildx build \
               -t wildme/scoutbot:latest \
               --platform linux/amd64 \
               --push \

.github/workflows/python-publish.yml

@@ -67,8 +67,8 @@ jobs:
     env:
       WIC_BATCH_SIZE: 16
 
-    # upload to PyPI on every tag starting with 'v'
-    if: github.event_name == 'push'  # && startsWith(github.event.ref, 'refs/tags/v')
+    # test wheel
+    if: github.event_name == 'push'
     steps:
       - uses: actions/setup-python@v2
         name: Install Python
@@ -95,19 +95,19 @@ jobs:
           scoutbot fetch
           scoutbot example
 
-  # upload_pypi:
-  #   needs: [test_wheel]
-  #   runs-on: ubuntu-latest
-  #   # upload to PyPI on every tag starting with 'v'
-  #   if: github.event_name == 'push'  # && startsWith(github.event.ref, 'refs/tags/v')
-  #   steps:
-  #     - uses: actions/download-artifact@v2
-  #       with:
-  #         name: artifact
-  #         path: dist
-
-  #     - uses: pypa/gh-action-pypi-publish@release/v1
-  #       with:
-  #         user: __token__
-  #         password: ${{ secrets.PYPI_PASSWORD }}
-  #         # To test: repository_url: https://test.pypi.org/legacy/
+  upload_pypi:
+    needs: [test_wheel]
+    runs-on: ubuntu-latest
+    # upload to PyPI on every tag starting with 'v'
+    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/download-artifact@v2
+        with:
+          name: artifact
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_PASSWORD }}
+          # To test: repository_url: https://test.pypi.org/legacy/

CHANGELOG.rst

@@ -5,21 +5,32 @@ Changelog
 Version 0.1.17
 --------------
 
-- **[BREAKING CHANGE]** Added detection label mapping for the ``phase1`` output to rename ``elephant_savanna`` to ``elephant``
-  to be consistent with the ``mvp`` output labels.
-- Added rounding to the WIC predicted confidence to 4 decimal points in the print and JSON outputs.
-- Added to the documentation the list of supported class labels for each model configuration.
-- Added platform detection code to detect macOS and reduce the batch size of WIC models with the
+* **[BREAKING CHANGE]** Added detection label mapping for the ``phase1`` output to rename the following species labels to be consistent with the ``mvp`` output labels:
+
+    * ``elephant_savanna`` to ``elephant``
+    * ``dead_animalwhite_bones`` to ``white_bones``
+    * ``deadbones`` to ``white_bones``
+    * ``elecarcass_old`` to ``white_bones``
+    * ``gazelle_gr`` to ``gazelle_grants``
+    * ``gazelle_th`` to ``gazelle_thomsons``
+
+* Added rounding to the WIC predicted confidence to 4 decimal points in the print and JSON outputs.
+* Added to the documentation the list of supported class labels for each model configuration.
+* Updated the documentation to highlight the list of recommended supported species for the MVP model
+  (based on held-out validation data), and to add the build and deployment instructions.
+* Added platform detection code to detect macOS and reduce the batch size of WIC models with the
   MVP model to 1 (added to Known Issues).
-- Added three new environment variables to allow specifying the model configuration for the ``WIC``,
+* Added three new environment variables to allow specifying the model configuration for the ``WIC``,
   ``LOC``, and ``AGG``, respectively: ``WIC_CONFIG``, ``LOC_CONFIG``, ``AGG_CONFIG``.  If unset, it
   uses the global config and behavior as specified by the ``CONFIG`` environment variable.  The TILE
   module does not have different settings dependent on the model configuration.
-- Added a new environment variable to allow for faster but less accurate results: ``FAST``.  If unset, it
+* Added a new environment variable to allow for faster but less accurate results: ``FAST``.  If unset, it
   uses the standard tile extraction behavior for grid1 and grid2.  Turning this flag on will dramatically
   speed up inference by processing approximately half of the number of tiles per image.
-- Added ``CHANGELOG.rst`` and ``ISSUES.rst``.
-- Modified documentation strings in a few places for clarity and correctness.
+* Added ``CHANGELOG.rst`` and ``ISSUES.rst``.
+* Modified documentation strings in a few places for clarity and correctness.
+* Updated both Gradio apps to support the Phase1 and MVP models and their respective configurations.
+* Updated tests to support the new ML configuration default settings.
 
 Version 0.1.16
 --------------

README.rst

@@ -12,46 +12,43 @@ Wild Me ScoutBot
 How to Install
 --------------
 
-.. code-block:: console
+.. code-block:: bash
 
-    (.venv) $ pip install scoutbot
+    pip install scoutbot
 
 or, from source:
 
-.. code-block:: console
+.. code-block:: bash
 
    git clone https://github.com/WildMeOrg/scoutbot
    cd scoutbot
-   (.venv) $ pip install -e .
+   pip install -e .
 
 To then add GPU acceleration, you need to replace `onnxruntime` with `onnxruntime-gpu`:
 
-.. code-block:: console
+.. code-block:: bash
 
-   (.venv) $ pip uninstall -y onnxruntime
-   (.venv) $ pip install onnxruntime-gpu
+   pip uninstall -y onnxruntime
+   pip install onnxruntime-gpu
 
 How to Run
 ----------
 
 You can run the tile-based Gradio demo with:
 
-.. code-block:: console
+.. code-block:: bash
 
-   (.venv) $ python app.py
+   python app.py
 
 or, you can run the image-based Gradio demo with:
 
-.. code-block:: console
+.. code-block:: bash
 
-   (.venv) $ python app2.py
-
-Docker
-------
+   python app2.py
 
 To run with Docker:
 
-.. code-block:: console
+.. code-block:: bash
 
     docker run \
        -it \
@@ -90,9 +87,17 @@ To run with Docker Compose:
 
 and run ``docker compose up -d``.
 
-The application can also be built into a Docker image and is hosted on Docker Hub as ``wildme/scoutbot:latest``.
+How to Build and Deploy
+-----------------------
+
+Docker Hub
+==========
+
+The application can also be built into a Docker image and is hosted on Docker Hub as ``wildme/scoutbot:latest``.  Any time the ``main`` branch is updated or a tagged release is made (see the PyPI instructions below), an automated GitHub CD action will build and deploy the newest image to Docker Hub automatically.
 
-.. code-block:: console
+To do this manually, use the code below:
+
+.. code-block:: bash
 
     docker login
 
@@ -106,21 +111,53 @@ The application can also be built into a Docker image and is hosted on Docker Hu
         --push \
         .
 
+PyPI
+====
+
+To upload the latest ScoutBot version to the Python Package Index (PyPI), follow the steps below:
+
+#. Edit ``scoutbot/__init__.py:65`` and set ``VERSION`` to the desired version
+
+    .. code-block:: python
+
+        VERSION = 'X.Y.Z'
+
+
+#. Push any changes and version update to the ``main`` branch on GitHub and wait for CI tests to pass
+
+    .. code-block:: bash
+
+        git pull origin main
+        git commit -am "Release for Version X.Y.Z"
+        git push origin main
+
+
+#. Tag the ``main`` branch as a new release using the `SemVer pattern <https://semver.org/>`_ (e.g., ``vX.Y.Z``)
+
+    .. code-block:: bash
+
+        git pull origin main
+        git tag vX.Y.Z
+        git push origin vX.Y.Z
+
+
+#. Wait for the automated GitHub CD actions to build and push to `PyPI <https://pypi.org/project/scoutbot/>`_ and `Docker Hub <https://hub.docker.com/r/wildme/scoutbot>`_.
+
 Tests and Coverage
 ------------------
 
 You can run the automated tests in the ``tests/`` folder by running:
 
-.. code-block:: console
+.. code-block:: bash
 
-    (.venv) $ pip install -r requirements.optional.txt
-    (.venv) $ pytest
+    pip install -r requirements.optional.txt
+    pytest
 
 You may also get a coverage percentage by running:
 
-.. code-block:: console
+.. code-block:: bash
 
-    (.venv) $ coverage html
+    coverage html
 
 and open the `coverage/html/index.html` file in your browser.
 
@@ -129,19 +166,19 @@ Building Documentation
 
 There is Sphinx documentation in the ``docs/`` folder, which can be built by running:
 
-.. code-block:: console
+.. code-block:: bash
 
-    (.venv) $ cd docs/
-    (.venv) $ pip install -r requirements.optional.txt
-    (.venv) $ sphinx-build -M html . build/
+    cd docs/
+    pip install -r requirements.optional.txt
+    sphinx-build -M html . build/
 
 Logging
 -------
 
 The script uses Python's built-in logging functionality called ``logging``.  All print functions are replaced with ``log.info()``, which sends the output to two places:
 
-    - 1. the terminal window, and
-    - 2. the file `scoutbot.log`
+#. the terminal window, and
+#. the file `scoutbot.log`
 
 Code Formatting
 ---------------
@@ -151,10 +188,10 @@ on any code you write.  See `pre-commit.com <https://pre-commit.com/>`_ for more
 
 Reference `pre-commit's installation instructions <https://pre-commit.com/#install>`_ for software installation on your OS/platform. After you have the software installed, run ``pre-commit install`` on the command line. Now every time you commit to this project's code base the linter procedures will automatically run over the changed files.  To run pre-commit on files preemtively from the command line use:
 
-.. code-block:: console
+.. code-block:: bash
 
-    (.venv) $ pip install -r requirements.optional.txt
-    (.venv) $ pre-commit run --all-files
+    pip install -r requirements.optional.txt
+    pre-commit run --all-files
 
 The code base has been formatted by `Brunette <https://pypi.org/project/brunette/>`_, which is a fork and more configurable version of `Black <https://black.readthedocs.io/en/stable/>`_.  Furthermore, try to conform to ``PEP8``.  You should set up your preferred editor to use ``flake8`` as its Python linter, but pre-commit will ensure compliance before a git commit is completed.  This will use the ``flake8`` configuration within ``setup.cfg``, which ignores several errors and stylistic considerations.  See the ``setup.cfg`` file for a full and accurate listing of stylistic codes to ignore.