From 8d2473c751ca53fd22164a51b66bbd7fa13375f1 Mon Sep 17 00:00:00 2001
From: Mark McDonald <macd@google.com>
Date: Thu, 15 Dec 2022 15:42:00 -0800
Subject: [PATCH] Update `Image` docs to improve rendering.

The [API docs](https://developers.google.com/mediapipe/api/solutions/python/mp/Image) have a few rendering issues. e.g., the doc generator will turn
```
This block:
  Anything here
```
Into a table with heading `This block` and `Anything here` as a plain-text cell.

In order to render code as code, it needs to be in backticks. They can also be in `>>> code()` format, and we can try to run them ([doctests](https://docs.python.org/3/library/doctest.html)).

I'll have a dashboard ready soon that shows areas we can improve.

PiperOrigin-RevId: 495715576
---
 mediapipe/python/pybind/image.cc | 46 ++++++++++++++++++++------------
 1 file changed, 29 insertions(+), 17 deletions(-)

diff --git a/mediapipe/python/pybind/image.cc b/mediapipe/python/pybind/image.cc
index 5d8663143..e5fa24e8c 100644
--- a/mediapipe/python/pybind/image.cc
+++ b/mediapipe/python/pybind/image.cc
@@ -48,16 +48,19 @@ void ImageSubmodule(pybind11::module* module) {
   become immutable after creation.
 
   Creation examples:
-    import cv2
-    cv_mat = cv2.imread(input_file)[:, :, ::-1]
-    rgb_frame = mp.Image(format=ImageFormat.SRGB, data=cv_mat)
-    gray_frame = mp.Image(
-        format=ImageFormat.GRAY, data=cv2.cvtColor(cv_mat, cv2.COLOR_RGB2GRAY))
 
-    from PIL import Image
-    pil_img = Image.new('RGB', (60, 30), color = 'red')
-    image = mp.Image(
-        format=mp.ImageFormat.SRGB, data=np.asarray(pil_img))
+  ```python
+  import cv2
+  cv_mat = cv2.imread(input_file)[:, :, ::-1]
+  rgb_frame = mp.Image(format=ImageFormat.SRGB, data=cv_mat)
+  gray_frame = mp.Image(
+      format=ImageFormat.GRAY, data=cv2.cvtColor(cv_mat, cv2.COLOR_RGB2GRAY))
+
+  from PIL import Image
+  pil_img = Image.new('RGB', (60, 30), color = 'red')
+  image = mp.Image(
+      format=mp.ImageFormat.SRGB, data=np.asarray(pil_img))
+  ```
 
   The pixel data in an Image can be retrieved as a numpy ndarray by calling
   `Image.numpy_view()`. The returned numpy ndarray is a reference to the
@@ -65,15 +68,18 @@ void ImageSubmodule(pybind11::module* module) {
   numpy ndarray, it's required to obtain a copy of it.
 
   Pixel data retrieval examples:
-    for channel in range(num_channel):
-      for col in range(width):
-        for row in range(height):
-          print(image[row, col, channel])
 
-    output_ndarray = image.numpy_view()
-    print(output_ndarray[0, 0, 0])
-    copied_ndarray = np.copy(output_ndarray)
-    copied_ndarray[0,0,0] = 0
+  ```python
+  for channel in range(num_channel):
+    for col in range(width):
+      for row in range(height):
+        print(image[row, col, channel])
+
+  output_ndarray = image.numpy_view()
+  print(output_ndarray[0, 0, 0])
+  copied_ndarray = np.copy(output_ndarray)
+  copied_ndarray[0,0,0] = 0
+  ```
   )doc",
       py::dynamic_attr());
 
@@ -156,9 +162,11 @@ void ImageSubmodule(pybind11::module* module) {
     An unwritable numpy ndarray.
 
   Examples:
+    ```
     output_ndarray = image.numpy_view()
     copied_ndarray = np.copy(output_ndarray)
     copied_ndarray[0,0,0] = 0
+    ```
 )doc");
 
   image.def(
@@ -191,10 +199,12 @@ void ImageSubmodule(pybind11::module* module) {
     IndexError: If the index is invalid or out of bounds.
 
   Examples:
+    ```
     for channel in range(num_channel):
       for col in range(width):
         for row in range(height):
           print(image[row, col, channel])
+    ```
 )doc");
 
   image
@@ -224,7 +234,9 @@ void ImageSubmodule(pybind11::module* module) {
     A boolean.
 
   Examples:
+    ```
     image.is_aligned(16)
+    ```
 )doc");
 
   image.def_static(