Merge pull request #9 from agfianf/docs/complete-docstring

Docs/complete docstring

Author: agfianf

.github/workflows/docs.yml

@@ -18,30 +18,29 @@ jobs:
       id-token: write
       actions: read
     steps:
-      - name: Clone repository
+      - name: 🗃️ Clone repository
         uses: actions/checkout@v4
 
-      - name: Install uv and set the python version
+      - name: 🐍 Install uv and set the python version
         uses: astral-sh/setup-uv@v5
         with:
           version: "0.5.24"
           enable-cache: true
           cache-dependency-glob: "uv.lock"
           python-version: 3.12
 
-
-      - name: Install dependencies
+      - name: 📦 Install dependencies
         run: |
           uv sync --only-group docs
 
-      - name: Build MkDocs site
+      - name: 🏗️ Build MkDocs site
         run: |
           mkdocs build
 
-      - name: Setup Pages
+      - name: 🔧 Setup Pages
         uses: actions/configure-pages@v3
 
-      - name: Upload artifact
+      - name: 📤 Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: ./site
@@ -61,6 +60,6 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
 
     steps:
-      - name: Deploy to GitHub Pages
+      - name: 🚀 Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.github/workflows/tests.yml

@@ -5,12 +5,16 @@ on:
     branches: [ main ]
     paths-ignore:
       - '**.md'
+      - '*.md'
+      - '**.js'
+      - '**.html'
+      - '**.css'
       - 'docs/**'
       - 'LICENSE'
       - '.gitignore'
       - '.pre-commit-config.yaml'
       - 'mkdocs.yml'
-      - 'docs_requirements.txt'
+      - 'CHANGELOG.md'
 
 jobs:
   test:

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [v0.0.1-rc1] - 2025-02-10
+**Release Candidate with Full Feature Set and Documentation**
+- Add docs page build with mkdocs-material. Read more [https://agfianf.github.io/color-correction/](https://agfianf.github.io/color-correction/)
+- Complete docstrings for all classes and methods
+
 ## [v0.0.1b3] - 2025-02-06
 **Add Analyzer Report and Bug Fixes**
 

Makefile

@@ -19,3 +19,12 @@ log:
 
 update-uv-lock:
 	uv lock
+
+list-installed:
+	uv pip list
+
+sync-docs:
+	uv sync --only-group={docs,dev}
+
+sync-all:
+	uv sync --all-groups  --no-group dev-model

color_correction/core/correction/polynomial.py

@@ -20,8 +20,9 @@ class Polynomial(BaseComputeCorrection):
     ----------
     **kwargs : dict, optional
         Keyword arguments. Recognized keyword:
-        degree : int, optional, default 2
-            Degree of the polynomial.
+
+        - `degree` : int, optional, default 2
+             Degree of the polynomial.
     """
 
     def __init__(self, **kwargs: dict) -> None:
@@ -60,17 +61,15 @@ def fit(
             Reference image patches.
         **kwargs : dict
             Additional keyword arguments. Recognized keyword:
-            degree : int, optional
-                Degree of the polynomial.
+
+            - `degree` : int, optional
+                 Degree of the polynomial.
 
         Returns
         -------
         np.ndarray
             Fitted model pipeline.
 
-        Notes
-        -----
-        The execution time for model fitting is printed.
         """
         start_time = time.perf_counter()
         degree = kwargs.get("degree", self.degree)

color_correction/schemas/__init__.py

@@ -0,0 +1,70 @@
+"""
+Images Schema Module
+--------------------
+This module defines type annotations for image processing.
+
+Attributes
+----------
+ColorPatchType : numpy.typing.NDArray[np.uint8]
+    Represents a color patch extracted from an image. Usually a mean of a region patch.
+
+    Example
+    -------
+    ```python
+    np.array(
+        [
+            [68, 82, 115],  # 1. Dark skin
+            [128, 149, 195],  # 2. Light skin
+            [157, 123, 93],  # 3. Blue sky
+            [65, 108, 91],  # 4. Foliage
+            [175, 129, 130],  # 5. Blue flower
+            [171, 191, 99],  # 6. Bluish green
+            [46, 123, 220],  # 7. Orange
+            [168, 92, 72],  # 8. Purplish blue
+            [97, 84, 194],  # 9. Moderate red
+            [104, 59, 91],  # 10. Purple
+            [62, 189, 161],  # 11. Yellow green
+            [40, 161, 229],  # 12. Orange yellow
+            [147, 63, 42],  # 13. Blue
+            [72, 149, 72],  # 14. Green
+            [57, 50, 175],  # 15. Red
+            [22, 200, 238],  # 16. Yellow
+            [150, 84, 188],  # 17. Magenta
+            [166, 137, 0],  # 18. Cyan
+            [240, 245, 245],  # 19. White 9.5
+            [201, 202, 201],  # 20. Neutral 8
+            [162, 162, 161],  # 21. Neutral 6.5
+            [121, 121, 120],  # 22. Neutral 5
+            [85, 85, 83],  # 23. Neutral 3.5
+            [51, 50, 50],  # 24. Black 2
+        ],
+    )
+    ```
+ImageType : numpy.typing.NDArray[np.uint8]
+    Represents an image 3D array with shape (H, W, C) in uint8 format.
+ImageBGR : numpy.typing.NDArray[np.uint8]
+    Represents an image in BGR format (OpenCV default).
+ImageRGB : numpy.typing.NDArray[np.uint8]
+    Represents an image in RGB format.
+
+"""
+
+from typing import Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+LiteralModelCorrection = Literal[
+    "least_squares",
+    "polynomial",
+    "linear_reg",
+    "affine_reg",
+]
+
+LiteralModelDetection = Literal["yolov8"]
+
+ColorPatchType = NDArray[np.uint8]
+ImageType = NDArray[np.uint8]
+ImageBGR = NDArray[np.uint8]
+ImageRGB = NDArray[np.uint8]
+ImageGray = NDArray[np.uint8]

color_correction/schemas/custom_types.py

@@ -1,3 +1,10 @@
+"""
+Module for detection result schema using Pydantic.
+
+Provides the DetectionResult model that contains detection boxes, scores, and class ids,
+and a helper method to draw these detections on an image.
+"""
+
 import numpy as np
 from pydantic import BaseModel
 
@@ -7,6 +14,38 @@
 
 
 class DetectionResult(BaseModel):
+    """
+    Detection result model for YOLOv8 card and color patches detection.
+
+    A data model that encapsulates YOLOv8 detection results for a standardized color
+    card and its color patches. The model handles two distinct classes:
+    patches (label 0) and card (label 1). In a typical detection scenario,
+    the model captures one color calibration card and 24 color patches.
+
+
+    Notes
+    -----
+    The detection typically yields 25 objects:
+
+    - 1 calibration card (class_id: 1)
+    - 24 color patches (class_id: 0)
+
+    Attributes
+    ----------
+    boxes : list[tuple[int, int, int, int]]
+        List of bounding boxes as (x1, y1, x2, y2).
+        Representing the top-left and bottom-right corners of the detection.
+        Class identifiers for each detected object where:
+
+        - 0: represents color patches
+        - 1: represents the calibration card
+
+    scores : list[float]
+        List of confidence scores for each detection.
+    class_ids : list[int]
+        List of class IDs corresponding to each detection.
+    """
+
     boxes: list[BoundingBox]
     scores: list[float]
     class_ids: list[int]
@@ -15,5 +54,17 @@ def draw_detections(
         self,
         image: np.ndarray,
     ) -> np.ndarray:
-        """Draw detection boxes on image."""
+        """
+        Draw detection boxes on the provided image.
+
+        Parameters
+        ----------
+        image : numpy.ndarray
+            The image on which the detection boxes will be drawn.
+
+        Returns
+        -------
+        numpy.ndarray
+            The image with the drawn detection boxes.
+        """
         return draw_detections(image, self.boxes, self.scores, self.class_ids)

color_correction/schemas/det_yv8.py

@@ -19,7 +19,20 @@ class CPUArchitecture(str, Enum):
 
 
 class DeviceSpecs(BaseModel):
-    """Device specifications schema."""
+    """
+    Device specifications schema.
+
+    Attributes
+    ----------
+    os_name : str
+        Operating system name.
+    cpu_arch : CPUArchitecture
+        CPU architecture.
+    gpu_type : GPUType
+        GPU type.
+    is_apple_silicon : bool
+        Whether the device is Apple Silicon.
+    """
 
     os_name: str = Field(..., description="Operating system name")
     cpu_arch: CPUArchitecture = Field(