From 83d490dadcdda50d29248f7e82d28dc4683efaa0 Mon Sep 17 00:00:00 2001
From: SkalskiP <piotr.skalski92@gmail.com>
Date: Wed, 6 Aug 2025 23:19:21 +0200
Subject: [PATCH] initial support for `pycon` docs examples

---
 docs/stylesheets/code_select.css              |  3 ++
 ...{cookbooks-card.css => cookbooks_card.css} |  0
 mkdocs.yml                                    |  6 ++-
 supervision/draw/utils.py                     | 42 ++++++++++++++-----
 4 files changed, 39 insertions(+), 12 deletions(-)
 create mode 100644 docs/stylesheets/code_select.css
 rename docs/stylesheets/{cookbooks-card.css => cookbooks_card.css} (100%)

diff --git a/docs/stylesheets/code_select.css b/docs/stylesheets/code_select.css
new file mode 100644
index 00000000..dce599a2
--- /dev/null
+++ b/docs/stylesheets/code_select.css
@@ -0,0 +1,3 @@
+.language-pycon .gp, .language-pycon .go {
+    user-select: none;
+}
\ No newline at end of file
diff --git a/docs/stylesheets/cookbooks-card.css b/docs/stylesheets/cookbooks_card.css
similarity index 100%
rename from docs/stylesheets/cookbooks-card.css
rename to docs/stylesheets/cookbooks_card.css
diff --git a/mkdocs.yml b/mkdocs.yml
index 394d5ddd..612f8901 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -26,7 +26,8 @@ extra:
 
 extra_css:
   - stylesheets/extra.css
-  - stylesheets/cookbooks-card.css
+  - stylesheets/cookbooks_card.css
+  - stylesheets/code_select.css
 
 nav:
   - Home: index.md
@@ -169,6 +170,7 @@ markdown_extensions:
   - pymdownx.snippets:
       check_paths: true
   - pymdownx.highlight:
+      use_pygments: true
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
@@ -190,4 +192,4 @@ validation:
   nav:
     absolute_links: ignore
   links:
-    absolute_links: ignore
+    absolute_links: ignore
\ No newline at end of file
diff --git a/supervision/draw/utils.py b/supervision/draw/utils.py
index ed4a9037..536e493f 100644
--- a/supervision/draw/utils.py
+++ b/supervision/draw/utils.py
@@ -346,28 +346,50 @@ def draw_image(
 
 def calculate_optimal_text_scale(resolution_wh: tuple[int, int]) -> float:
     """
-    Calculate font scale based on the resolution of an image.
+    Calculate optimal font scale based on image resolution.
 
-    Parameters:
-        resolution_wh (Tuple[int, int]): A tuple representing the width and height
-            of the image.
+    Adjusts font scale proportionally to the smallest dimension of the given image
+    resolution for consistent readability.
+
+    Args:
+        resolution_wh (tuple[int, int]): (width, height) of the image in pixels
 
     Returns:
-         float: The calculated font scale factor.
+        float: recommended font scale factor
+
+    Examples:
+        ```pycon
+        >>> from supervision import calculate_optimal_text_scale
+        >>> calculate_optimal_text_scale((1920, 1080))
+        1.08
+        >>> calculate_optimal_text_scale((640, 480))
+        0.48
+        ```
     """
     return min(resolution_wh) * 1e-3
 
 
 def calculate_optimal_line_thickness(resolution_wh: tuple[int, int]) -> int:
     """
-    Calculate line thickness based on the resolution of an image.
+    Calculate optimal line thickness based on image resolution.
 
-    Parameters:
-        resolution_wh (Tuple[int, int]): A tuple representing the width and height
-            of the image.
+    Adjusts the line thickness for readability depending on the smallest dimension
+    of the provided image resolution.
+
+    Args:
+        resolution_wh (tuple[int, int]): (width, height) of the image in pixels
 
     Returns:
-        int: The calculated line thickness in pixels.
+        int: recommended line thickness in pixels
+
+    Examples:
+        ```pycon
+        >>> from supervision import calculate_optimal_line_thickness
+        >>> calculate_optimal_line_thickness((1920, 1080))
+        4
+        >>> calculate_optimal_line_thickness((640, 480))
+        2
+        ```
     """
     if min(resolution_wh) < 1080:
         return 2