docs/ src/__init__.py: improve docs for insert_textbox() methods.

src/__init__.py:
    In Page.insert_textbox() and Shape.insert_textbox(), sort args to simplify
    comparison.

docs/shape.rst::insert_textbox():
    Use sorted multiple lines for args to simplify comparison.

docs/page.rst:insert_textbox():
    Use sorted multiple lines for args to simplify comparison.

    Describe <overlay> explicitly because not in Shape.insert_textbox().

    Fixed args to match the code:
    * Removed <charwidths>.
    * Removed <idx>.
    * Added <lineheight>.
    * Added <set_simple>.

Author: julian-smith-artifex-com

docs/page.rst

@@ -783,9 +783,34 @@ In a nutshell, this is what you can do with PyMuPDF:
       pair: fill_opacity; insert_textbox
       pair: oc; insert_textbox
 
-   .. method:: insert_textbox(rect, buffer, *, fontsize=11, fontname="helv", fontfile=None, idx=0, color=None, fill=None, render_mode=0, miter_limit=1, border_width=1, encoding=TEXT_ENCODING_LATIN, expandtabs=8, align=TEXT_ALIGN_LEFT, charwidths=None, rotate=0, morph=None, stroke_opacity=1, fill_opacity=1, oc=0, overlay=True)
-
-      PDF only: Insert text into the specified :data:`rect_like` *rect*. See :meth:`Shape.insert_textbox`.
+   .. method:: insert_textbox(rect, buffer, \
+                *, \
+                align=TEXT_ALIGN_LEFT, \
+                border_width=1, \
+                color=None, \
+                encoding=TEXT_ENCODING_LATIN, \
+                expandtabs=8, \
+                fill=None, \
+                fill_opacity=1, \
+                fontfile=None, \
+                fontname="helv", \
+                fontsize=11, \
+                lineheight=None, \
+                miter_limit=1, \
+                morph=None, \
+                oc=0, \
+                overlay=True, \
+                render_mode=0, \
+                rotate=0, \
+                set_simple=False, \
+                stroke_opacity=1, \
+                )
+
+      PDF only: Insert text into the specified :data:`rect_like` *rect*.
+      
+      :arg overlay: see :meth:`Shape.commit`.
+      
+      For other args, see `Shape.insert_textbox`.
 
       |history_begin|
 

docs/shape.rst

@@ -333,8 +333,30 @@ Several draw methods can be executed in a row and each one of them will contribu
       pair: rotate; insert_textbox
       pair: oc; insert_textbox
 
-   .. method:: insert_textbox(rect, buffer, *, fontsize=11, fontname="helv", fontfile=None, set_simple=False, encoding=TEXT_ENCODING_LATIN, color=None, fill=None, render_mode=0, miter_limit=1, border_width=1, expandtabs=8, align=TEXT_ALIGN_LEFT, rotate=0, lineheight=None, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)
-
+   .. method:: insert_textbox( \
+                rect, \
+                buffer, \
+                *, \
+                align=TEXT_ALIGN_LEFT, \
+                border_width=1, \
+                color=None, \
+                encoding=TEXT_ENCODING_LATIN, \
+                expandtabs=8, \
+                fill=None, \
+                fill_opacity=1, \
+                fontfile=None, \
+                fontname="helv", \
+                fontsize=11, \
+                lineheight=None, \
+                miter_limit=1, \
+                morph=None, \
+                oc=0, \
+                render_mode=0, \
+                rotate=0, \
+                set_simple=False, \
+                stroke_opacity=1, \
+                )
+      
       PDF only: Insert text into the specified rectangle. The text will be split into lines and words and then filled into the available space, starting from one of the four rectangle corners, which depends on `rotate`. Line feeds and multiple space will be respected.
 
       :arg rect_like rect: the area to use. It must be finite and not empty.
@@ -343,17 +365,18 @@ Several draw methods can be executed in a row and each one of them will contribu
 
       :arg int align: align each text line. Default is 0 (left). Centered, right and justified are the other supported options, see :ref:`TextAlign`. Please note that the effect of parameter value *TEXT_ALIGN_JUSTIFY* is only achievable with "simple" (single-byte) fonts (including the :ref:`Base-14-Fonts`).
 
-      :arg float lineheight: a factor to override the line height calculated from font properties. If not `None`, a line height of `fontsize * lineheight` will be used.
-
       :arg int expandtabs: controls handling of tab characters ``\t`` using the `string.expandtabs()` method **per each line**.
 
-      :arg float stroke_opacity: *(new in v1.18.1)* set transparency for stroke colors. Negative values and values > 1 will be ignored. Default is 1 (intransparent).
       :arg float fill_opacity: *(new in v1.18.1)* set transparency for fill colors. Default is 1 (intransparent). Use this value to control transparency of the text color. Stroke opacity **only** affects the border line of characters.
 
-      :arg int rotate: requests text to be rotated in the rectangle. This value must be a multiple of 90 degrees. Default is 0 (no rotation). Effectively, the four values `0`, `90`, `180` and `270` (= `-90`) are processed, each causing the text to start in a different rectangle corner. Bottom-left is `90`, bottom-right is `180`, and `-90 / 270` is top-right. See the example how text is filled in a rectangle. This argument takes precedence over morphing. See the second example, which shows text first rotated left by `90` degrees and then the whole rectangle rotated clockwise around is lower left corner.
+      :arg float lineheight: a factor to override the line height calculated from font properties. If not `None`, a line height of `fontsize * lineheight` will be used.
 
       :arg int oc: *(new in v1.18.4)* the :data:`xref` number of an :data:`OCG` or :data:`OCMD` to make this text conditionally displayable.
 
+      :arg int rotate: requests text to be rotated in the rectangle. This value must be a multiple of 90 degrees. Default is 0 (no rotation). Effectively, the four values `0`, `90`, `180` and `270` (= `-90`) are processed, each causing the text to start in a different rectangle corner. Bottom-left is `90`, bottom-right is `180`, and `-90 / 270` is top-right. See the example how text is filled in a rectangle. This argument takes precedence over morphing. See the second example, which shows text first rotated left by `90` degrees and then the whole rectangle rotated clockwise around is lower left corner.
+
+      :arg float stroke_opacity: *(new in v1.18.1)* set transparency for stroke colors. Negative values and values > 1 will be ignored. Default is 1 (intransparent).
+      
       :rtype: float
       :returns:
           **If positive or zero**: successful execution. The value returned is the unused rectangle line space in pixels. This may safely be ignored -- or be used to optimize the rectangle, position subsequent items, etc.

src/__init__.py

@@ -12620,25 +12620,25 @@ def insert_textbox(
             rect: rect_like,
             buffer: typing.Union[str, list],
             *,
-            fontname: str = "helv",
-            fontfile: OptStr = None,
-            set_simple: int = 0,
+            align: int = 0,
+            border_width: float = 0.05,
+            color: OptSeq = None,
             encoding: int = 0,
+            expandtabs: int = 1,
+            fill_opacity: float = 1,
+            fill: OptSeq = None,
+            fontfile: OptStr = None,
+            fontname: str = "helv",
             fontsize: float = 11,
             lineheight: OptFloat = None,
-            color: OptSeq = None,
-            fill: OptSeq = None,
-            expandtabs: int = 1,
-            align: int = 0,
-            rotate: int = 0,
-            render_mode: int = 0,
             miter_limit: float = 1,
-            border_width: float = 0.05,
             morph: OptSeq = None,
+            oc: int = 0,
             overlay: bool = True,
+            render_mode: int = 0,
+            rotate: int = 0,
+            set_simple: int = 0,
             stroke_opacity: float = 1,
-            fill_opacity: float = 1,
-            oc: int = 0,
             ) -> float:
         """Insert text into a given rectangle.
 
@@ -15390,24 +15390,24 @@ def insert_textbox(
         rect: rect_like,
         buffer: typing.Union[str, list],
         *,
-        fontname: OptStr = "helv",
+        align: int = 0,
+        border_width: float = 0.05,
+        color: OptSeq = None,
+        encoding: int = 0,
+        expandtabs: int = 1,
+        fill_opacity: float = 1,
+        fill: OptSeq = None,
         fontfile: OptStr = None,
+        fontname: OptStr = "helv",
         fontsize: float = 11,
         lineheight: OptFloat = None,
-        set_simple: bool = 0,
-        encoding: int = 0,
-        color: OptSeq = None,
-        fill: OptSeq = None,
-        expandtabs: int = 1,
-        border_width: float = 0.05,
         miter_limit: float = 1,
-        align: int = 0,
+        morph: OptSeq = None,
+        oc: int = 0,
         render_mode: int = 0,
         rotate: int = 0,
-        morph: OptSeq = None,
+        set_simple: bool = 0,
         stroke_opacity: float = 1,
-        fill_opacity: float = 1,
-        oc: int = 0,
     ) -> float:
         """Insert text into a given rectangle.