Merge pull request #991 from roboflow/develop

`supervision-0.19.0` release

Author: SkalskiP

.github/workflows/docs.yml

@@ -1,10 +1,8 @@
-name: Docs WorkFlow
+name: Docs WorkFlow - Develop Tag 📚
 
 on:
   push:
     branches:
-      - master
-      - main
       - develop
 
 permissions:
@@ -16,11 +14,34 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - name: 🔄 Checkout code
+        uses: actions/checkout@v4
         with:
-          python-version: 3.x
-      - run: pip install mkdocs-material
-      - run: pip install "mkdocstrings[python]"
-      - run: pip install "mkdocs-material[imaging]"
-      - run: mkdocs gh-deploy --force
+          fetch-depth: 0
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: 📦 Install mkdocs-material
+        run: pip install "mkdocs-material[all]"
+      - name: 📦 Install mkdocstrings[python]
+        run: pip install "mkdocstrings[python]"
+      - name: 📦 Install mkdocs-material[imaging]
+        run: pip install "mkdocs-material[imaging]"
+      - name: 📦 Install mike
+        run: pip install "mike"
+      - name: 📦 Install mkdocs-git-revision-date-localized-plugin
+        run: pip install "mkdocs-git-revision-date-localized-plugin"
+      - name: 📦 Install JupyterLab
+        run: pip install jupyterlab
+      - name: 📦 Install mkdocs-jupyter
+        run: pip install mkdocs-jupyter
+      - name: 📦 Install mkdocs-git-committers-plugin-2
+        run: pip install mkdocs-git-committers-plugin-2
+      - name: ⚙️ Configure git for github-actions
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: 🚀 Deploy MkDoc-Material with mike
+        run: |
+          MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} mike deploy --push develop

.github/workflows/publish.yml

@@ -3,8 +3,6 @@ on:
   push:
     tags:
       - '[0-9]+.[0-9]+[0-9]+.[0-9]'
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

.github/workflows/test-doc.yml

@@ -0,0 +1,34 @@
+name: 🧪 Docs Test WorkFlow 📚
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  docs-build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🔄 Checkout code
+        uses: actions/checkout@v4
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: 📦 Install mkdocs-material
+        run: pip install "mkdocs-material[all]"
+      - name: 📦 Install mkdocstrings[python]
+        run: pip install "mkdocstrings[python]"
+      - name: 📦 Install mkdocs-material[imaging]
+        run: pip install "mkdocs-material[imaging]"
+      - name: 📦 Install mike
+        run: pip install "mike"
+      - name: 📦 Install mkdocs-git-revision-date-localized-plugin
+        run: pip install "mkdocs-git-revision-date-localized-plugin"
+      - name: 📦 Install JupyterLab
+        run: pip install jupyterlab
+      - name: 📦 Install mkdocs-jupyter
+        run: pip install mkdocs-jupyter
+      - name: 📦 Install mkdocs-git-committers-plugin-2
+        run: pip install mkdocs-git-committers-plugin-2
+      - name: 🧪 Test documentation build
+        run: mkdocs build --verbose

.github/workflows/test-min.yml

@@ -37,6 +37,7 @@ jobs:
               matplotlib==3.5.0 \
               numpy==1.21.2 \
               opencv-python==4.5.5.64 \
+              Pillow==10.1.0 \
               packaging==23.2 \
               pluggy==1.3.0 \
               pyparsing==3.1.1 \

.gitignore

@@ -133,9 +133,6 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
-# Notebooks
-notebooks/
-
 # OSX folder attributes
 .DS_Store
 .AppleDouble

.pre-commit-config.yaml

@@ -14,7 +14,6 @@ repos:
         exclude: test/.*\.py
       - id: check-yaml
         exclude: mkdocs.yml
-      - id: check-docstring-first
       - id: check-executables-have-shebangs
       - id: check-toml
       - id: check-case-conflict
@@ -30,7 +29,7 @@ repos:
 
 
   -   repo: https://github.com/PyCQA/bandit
-      rev: '1.7.6'
+      rev: '1.7.8'
       hooks:
       -   id: bandit
           args: ["-c", "pyproject.toml"]
@@ -47,7 +46,7 @@ repos:
 
 
   -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.1.14
+      rev: v0.3.2
       hooks:
       -   id: ruff
           args: [--fix, --exit-non-zero-on-fix]

CITATION.cff

@@ -15,7 +15,7 @@ url: 'https://roboflow.github.io/supervision/'
 abstract: >-
   supervision features a range of utilities for use in
   computer vision projects, from detections processing and
-  filtering to confusion matrix calcuation.
+  filtering to confusion matrix calculation.
 keywords:
   - computer vision
   - image processing

CONTRIBUTING.md

@@ -112,6 +112,20 @@ To run the documentation, install the project requirements with `poetry install
 
 You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).
 
+## 🧑‍🍳 cookbooks
+
+We are always looking for new examples and cookbooks to add to the `supervision`
+documentation. If you have a use case that you think would be helpful to others, please
+submit a PR with your example. Here are some guidelines for submitting a new example:
+
+- Create a new notebook in the [`docs/nodebooks`](https://github.com/roboflow/supervision/tree/develop/docs/notebooks) folder.
+- Add a link to the new notebook in [`docs/theme/cookbooks.html`](https://github.com/roboflow/supervision/blob/develop/docs/theme/cookbooks.html). Make sure to add the path to the new notebook, as well as a title, labels, author and supervision version.
+- Use the [Count Objects Crossing the Line](https://supervision.roboflow.com/develop/notebooks/count-objects-crossing-the-line/) example as a template for your new example.
+- Freeze the version of `supervision` you are using.
+- Place an appropriate Open in Colab button at the top of the notebook. You can find an example of such a button in the aforementioned `Count Objects Crossing the Line` cookbook.
+- Notebook should be self-contained. If you rely on external data ( videos, images, etc.) or libraries, include download and installation commands in the notebook.
+- Annotate the code with appropriate comments, including links to the documentation describing each of the tools you have used.
+
 ## 🧪 tests
 
 [`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests.

README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <p>
-    <a align="center" href="" target="_blank">
+    <a align="center" href="" target="https://supervision.roboflow.com">
       <img
         width="100%"
         src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529"
@@ -10,7 +10,7 @@
 
   <br>
 
-[notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [collect](https://github.com/roboflow/roboflow-collect)
+[notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [maestro](https://github.com/roboflow/multimodal-maestro)
 
   <br>
 
@@ -21,13 +21,15 @@
 [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/main/demo.ipynb)
 [![Gradio](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Roboflow/Annotators)
 [![Discord](https://img.shields.io/discord/1159501506232451173)](https://discord.gg/GbfgXGJ8Bk)
-
+[![Built with Material for MkDocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
 </div>
 
 ## 👋 hello
 
 **We write your reusable computer vision tools.** Whether you need to load your dataset from your hard drive, draw detections on an image or video, or count how many detections are in a zone. You can count on us! 🤝
 
+[![supervision-hackfest](https://github.com/roboflow/supervision/assets/26109316/c05cc954-b9a6-4ed5-9a52-d0b4b619ff65)](https://github.com/orgs/roboflow/projects/10)
+
 ## 💻 install
 
 Pip install the supervision package in a
@@ -43,7 +45,7 @@ Read more about desktop, headless, and local installation in our [guide](https:/
 
 ### models
 
-Supervision was designed to be model agnostic. Just plug in any classification, detection, or segmentation model. For your convenience, we have created [connectors](https://supervision.roboflow.com/detection/core/#detections) for the most popular libraries like Ultralytics, Transformers, or MMDetection.
+Supervision was designed to be model agnostic. Just plug in any classification, detection, or segmentation model. For your convenience, we have created [connectors](https://supervision.roboflow.com/latest/detection/core/#detections) for the most popular libraries like Ultralytics, Transformers, or MMDetection.
 
 ```python
 import cv2
@@ -85,7 +87,7 @@ len(detections)
 
 ### annotators
 
-Supervision offers a wide range of highly customizable [annotators](https://supervision.roboflow.com/annotators/), allowing you to compose the perfect visualization for your use case.
+Supervision offers a wide range of highly customizable [annotators](https://supervision.roboflow.com/latest/annotators/), allowing you to compose the perfect visualization for your use case.
 
 ```python
 import cv2
@@ -105,7 +107,7 @@ https://github.com/roboflow/supervision/assets/26109316/691e219c-0565-4403-9218-
 
 ### datasets
 
-Supervision provides a set of [utils](https://supervision.roboflow.com/datasets/) that allow you to load, split, merge, and save datasets in one of the supported formats.
+Supervision provides a set of [utils](https://supervision.roboflow.com/latest/datasets/) that allow you to load, split, merge, and save datasets in one of the supported formats.
 
 ```python
 import supervision as sv