create stub doc files, refactor docstrings, add placeholders for examples

docs/draw.md

@@ -0,0 +1,9 @@
+Utilities for drawing on images.
+
+## Draw Line
+
+:::supervision.draw.utils.draw_line
+
+## Draw Rectangle
+
+:::supervision.draw.utils.draw_rectangle

docs/index.md

@@ -9,21 +9,22 @@
   </p>
 </div>
 
-## 👋 hello
+## 👋 Welcome
 
-A set of easy-to-use utils that will come in handy in any Computer Vision project. **Supervision** is still in 
+Supervision is a set of easy-to-use utilities that will come in handy in any computer vision project. 
-pre-release stage. 🚧 Keep your eyes open for potential bugs and be aware that at this stage our API is still fluid 
-and may change.
 
-## 💻 install
+**Supervision** is still in 
+pre-release stage 🚧 Keep your eyes open for potential bugs and be aware that at this stage our API is still fluid and may change.
 
-Pip install the supervision package in a
+## 💻 How to Install
+
+You can install `supervision` with pip in a 
 [**3.10>=Python>=3.7**](https://www.python.org/) environment.
 
 !!! example "Pip install method (recommended)"
 
     ```bash
-    pip install subervision
+    pip install supervision
     ```
 
 !!! example "Git clone method (for development)"

docs/notebook.md

@@ -0,0 +1,3 @@
+Utilities to help you build computer vision projects in notebook environments.
+
+:::supervision.notebook.utils.show_frame_in_notebook

docs/tools.md

@@ -0,0 +1,9 @@
+Useful utilities for common computer vision tasks.
+
+## Helper for Processing Model Detections
+
+:::supervision.tools.detections.Detections
+
+## Count Objects That Pass a Line
+
+:::supervision.tools.line_counter.LineCounter

mkdocs.yml

@@ -19,8 +19,12 @@ extra:
       link: https://twitter.com/roboflow
 
 nav:
-  - Home: index.md
+  - Home 🏠: index.md
-  - Video: video.md
+  - Video 📷: video.md
+  - Notebook Helpers 📓: notebook.md
+  - Draw 🎨: draw.md
+  - Geometry 📐: geometry.md
+  - Tools 🛠: tools.md
 
 theme:
   name: 'material'

supervision/draw/utils.py

@@ -11,12 +11,16 @@ def draw_line(
     """
     Draws a line on a given scene.
 
-    :param scene: np.ndarray : The scene on which the line will be drawn
+    Attributes:
-    :param start: Point : The starting point of the line
+
-    :param end: Point : The end point of the line
+        scene (np.ndarray): The scene on which the line will be drawn
-    :param color: Color : The color of the line
+        start (Point): The starting point of the line
-    :param thickness: int : The thickness of the line
+        end (Point): The end point of the line
-    :return: np.ndarray : The scene with the line drawn on it
+        color (Color): The color of the line
+        thickness (int): The thickness of the line
+
+    Returns:
+        np.ndarray: The scene with the line drawn on it
     """
     cv2.line(
         scene,
@@ -34,11 +38,19 @@ def draw_rectangle(
     """
     Draws a rectangle on an image.
 
-    :param scene: np.ndarray : The image on which to draw the rectangle.
+    Attributes:
-    :param rect: Rect : The rectangle to draw.
+        scene (np.ndarray): The scene on which the rectangle will be drawn
-    :param color: Color : The color of the rectangle.
+        rect (Rect): The rectangle to be drawn
-    :param thickness: int : The thickness of the rectangle border.
+        color (Color): The color of the rectangle
-    :return: np.ndarray : The image with the rectangle drawn on it.
+        thickness (int): The thickness of the rectangle border
+
+    Returns:
+        np.ndarray: The scene with the rectangle drawn on it
+
+    Example:
+        ```python
+        >>> # TODO: Add example
+        ```
     """
     cv2.rectangle(
         scene,
@@ -58,6 +70,20 @@ def draw_filled_rectangle(scene: np.ndarray, rect: Rect, color: Color) -> np.nda
     :param rect: Rect : The rectangle to be drawn.
     :param color: Color : The color of the rectangle.
     :return: np.ndarray : The updated scene with the filled rectangle drawn on it.
+
+    Attributes:
+        scene (np.ndarray): The scene on which the rectangle will be drawn
+        rect (Rect): The rectangle to be drawn
+        color (Color): The color of the rectangle
+
+    Returns:
+        np.ndarray: The scene with the rectangle drawn on it
+
+    Example:
+        ```python
+        >>> # TODO: Add example
+        ```
+    
     """
     cv2.rectangle(
         scene,

supervision/notebook/utils.py

@@ -11,9 +11,16 @@ def show_frame_in_notebook(
     """
     Display a frame in Jupyter Notebook using Matplotlib
 
-    :param frame: np.ndarray : The frame to be displayed.
+    Attributes:
-    :param size: Tuple[int, int] : The size of the plot. default:(10,10)
+        frame (np.ndarray): The frame to be displayed.
-    :param cmap: str : the colormap to use for single channel images. default:gray
+        size (Tuple[int, int]): The size of the plot. default:(10,10)
+        cmap (str): the colormap to use for single channel images. default:gray
+
+    Examples:
+        ```python
+        >>> from supervision.notebook import show_frame_in_notebook
+
+        ```
     """
     if frame.ndim == 2:
         plt.figure(figsize=size)

supervision/tools/detections.py

@@ -17,10 +17,11 @@ class Detections:
         """
         Data class containing information about the detections in a video frame.
 
-        :param xyxy: np.ndarray : An array of shape (n, 4) containing the bounding boxes coordinates in format [x1, y1, x2, y2]
+        Attributes:
-        :param confidence: np.ndarray : An array of shape (n,) containing the confidence scores of the detections.
+            xyxy (np.ndarray): An array of shape (n, 4) containing the bounding boxes coordinates in format [x1, y1, x2, y2]
-        :param class_id: np.ndarray : An array of shape (n,) containing the class ids of the detections.
+            confidence (np.ndarray): An array of shape (n,) containing the confidence scores of the detections.
-        :param tracker_id: Optional[np.ndarray] : An array of shape (n,) containing the tracker ids of the detections.
+            class_id (np.ndarray): An array of shape (n,) containing the class ids of the detections.
+            tracker_id (Optional[np.ndarray]): An array of shape (n,) containing the tracker ids of the detections.
         """
         self.xyxy: np.ndarray = xyxy
         self.confidence: np.ndarray = confidence
@@ -69,11 +70,17 @@ class Detections:
         """
         Creates a Detections instance from a YOLOv5 output tensor
 
-        :param yolov5_output: np.ndarray : The output tensor from YOLOv5
+        Attributes:
-        :return: Detections : A Detections instance representing the detections in the frame
+            yolov5_output (np.ndarray): The output tensor from YOLOv5
+        
+        Returns:
 
         Example:
-        detections = Detections.from_yolov5(yolov5_output)
+            ```python
+            >>> from supervision.tools.detections import Detections
+            
+            >>> detections = Detections.from_yolov5(yolov5_output)
+            ```
         """
         xyxy = yolov5_output[:, :4]
         confidence = yolov5_output[:, 4]
@@ -82,11 +89,14 @@ class Detections:
 
     def filter(self, mask: np.ndarray, inplace: bool = False) -> Optional[np.ndarray]:
         """
-        Filter the detections by applying a mask
+        Filter the detections by applying a mask.
 
-        :param mask: np.ndarray : A mask of shape (n,) containing a boolean value for each detection indicating if it should be included in the filtered detections
+        Attributes:
-        :param inplace: bool : If True, the original data will be modified and self will be returned.
+            mask (np.ndarray): A mask of shape (n,) containing a boolean value for each detection indicating if it should be included in the filtered detections
-        :return: Optional[np.ndarray] : A new instance of Detections with the filtered detections, if inplace is set to False. None otherwise.
+            inplace (bool): If True, the original data will be modified and self will be returned.
+
+        Returns:
+            Optional[np.ndarray]: A new instance of Detections with the filtered detections, if inplace is set to False. None otherwise.
         """
         if inplace:
             self.xyxy = self.xyxy[mask]
@@ -120,12 +130,14 @@ class BoxAnnotator:
         """
         A class for drawing bounding boxes on an image using detections provided.
 
-        :param color: Union[Color, ColorPalette] :  The color to draw the bounding box, can be a single color or a color palette
+        Attributes:
-        :param thickness: int :  The thickness of the bounding box lines, default is 2
+            color (Union[Color, ColorPalette]): The color to draw the bounding box, can be a single color or a color palette
-        :param text_color: Color :  The color of the text on the bounding box, default is white
+            thickness (int): The thickness of the bounding box lines, default is 2
-        :param text_scale: float :  The scale of the text on the bounding box, default is 0.5
+            text_color (Color): The color of the text on the bounding box, default is white
-        :param text_thickness: int :  The thickness of the text on the bounding box, default is 1
+            text_scale (float): The scale of the text on the bounding box, default is 0.5
-        :param text_padding: int :  The padding around the text on the bounding box, default is 5
+            text_thickness (int): The thickness of the text on the bounding box, default is 1
+            text_padding (int): The padding around the text on the bounding box, default is 5
+
         """
         self.color: Union[Color, ColorPalette] = color
         self.thickness: int = thickness
@@ -142,11 +154,14 @@ class BoxAnnotator:
     ) -> np.ndarray:
         """
         Draws bounding boxes on the frame using the detections provided.
+        
+        Attributes:
+            frame (np.ndarray): The image on which the bounding boxes will be drawn
+            detections (Detections): The detections for which the bounding boxes will be drawn
+            labels (Optional[List[str]]): An optional list of labels corresponding to each detection. If labels is provided, the confidence score of the detection will be replaced with the label.
 
-        :param frame: np.ndarray : The image on which the bounding boxes will be drawn
+        Returns:
-        :param detections: Detections : The detections for which the bounding boxes will be drawn
+            np.ndarray: The image with the bounding boxes drawn on it
-        :param labels: Optional[List[str]] :  An optional list of labels corresponding to each detection. If labels is provided, the confidence score of the detection will be replaced with the label.
-        :return: np.ndarray : The image with the bounding boxes drawn on it
         """
         font = cv2.FONT_HERSHEY_SIMPLEX
         for i, (xyxy, confidence, class_id, tracker_id) in enumerate(detections):

supervision/tools/line_counter.py

@@ -9,12 +9,17 @@ from supervision.tools.detections import Detections
 
 
 class LineCounter:
+    """
+    Count the number of objects that cross a line.
+    """
     def __init__(self, start: Point, end: Point):
         """
         Initialize a LineCounter object.
 
-        :param start: Point : The starting point of the line.
+        Attributes:
-        :param end: Point : The ending point of the line.
+            start (Point): The starting point of the line.
+            end (Point): The ending point of the line.
+
         """
         self.vector = Vector(start=start, end=end)
         self.tracker_state: Dict[str, bool] = {}
@@ -25,7 +30,9 @@ class LineCounter:
         """
         Update the in_count and out_count for the detections that cross the line.
 
-        :param detections: Detections : The detections for which to update the counts.
+        Attributes:
+            detections (Detections): The detections for which to update the counts.
+
         """
         for xyxy, confidence, class_id, tracker_id in detections:
             # handle detections with no tracker_id
@@ -77,13 +84,15 @@ class LineCounterAnnotator:
         """
         Initialize the LineCounterAnnotator object with default values.
 
-        :param thickness: float : The thickness of the line that will be drawn.
+        Attributes:
-        :param color: Color : The color of the line that will be drawn.
+            thickness (float): The thickness of the line that will be drawn.
-        :param text_thickness: float : The thickness of the text that will be drawn.
+            color (Color): The color of the line that will be drawn.
-        :param text_color: Color : The color of the text that will be drawn.
+            text_thickness (float): The thickness of the text that will be drawn.
-        :param text_scale: float : The scale of the text that will be drawn.
+            text_color (Color): The color of the text that will be drawn.
-        :param text_offset: float : The offset of the text that will be drawn.
+            text_scale (float): The scale of the text that will be drawn.
-        :param text_padding: int : The padding of the text that will be drawn.
+            text_offset (float): The offset of the text that will be drawn.
+            text_padding (int): The padding of the text that will be drawn.
+        
         """
         self.thickness: float = thickness
         self.color: Color = color
@@ -97,9 +106,13 @@ class LineCounterAnnotator:
         """
         Draws the line on the frame using the line_counter provided.
 
-        :param frame: np.ndarray : The image on which the line will be drawn
+        Attributes:
-        :param line_counter: LineCounter : The line counter that will be used to draw the line
+            frame (np.ndarray): The image on which the line will be drawn.
-        :return: np.ndarray : The image with the line drawn on it
+            line_counter (LineCounter): The line counter that will be used to draw the line.
+
+        Returns:
+            np.ndarray: The image with the line drawn on it.
+        
         """
         cv2.line(
             frame,