Merge pull request #6958 from radarhere/codeblock

docs/deprecations.rst

@@ -177,9 +177,7 @@ Deprecated                                                                  Use
 :py:meth:`.ImageDraw2.Draw.textsize`                                        :py:meth:`.ImageDraw2.Draw.textbbox` and :py:meth:`.ImageDraw2.Draw.textlength`
 =========================================================================== =============================================================================================================
 
-Previous code:
-
-.. code-block:: python
+Previous code::
 
     from PIL import Image, ImageDraw, ImageFont
 
@@ -194,9 +192,7 @@ Previous code:
     width, height = font.getsize_multiline("Hello\nworld")
     width, height = draw.multiline_textsize("Hello\nworld")
 
-Use instead:
-
-.. code-block:: python
+Use instead::
 
     from PIL import Image, ImageDraw, ImageFont
 
@@ -336,16 +332,12 @@ Implicitly closing the image's underlying file in ``Image.__del__`` has been rem
 Use a context manager or call ``Image.close()`` instead to close the file in a
 deterministic way.
 
-Previous method:
-
-.. code-block:: python
+Previous method::
 
     im = Image.open("hopper.png")
     im.save("out.jpg")
 
-Use instead:
-
-.. code-block:: python
+Use instead::
 
     with Image.open("hopper.png") as im:
         im.save("out.jpg")

docs/handbook/image-file-formats.rst

@@ -1393,9 +1393,7 @@ WMF, EMF
 Pillow can identify WMF and EMF files.
 
 On Windows, it can read WMF and EMF files. By default, it will load the image
-at 72 dpi. To load it at another resolution:
-
-.. code-block:: python
+at 72 dpi. To load it at another resolution::
 
     from PIL import Image
 
@@ -1404,9 +1402,7 @@ at 72 dpi. To load it at another resolution:
 
 To add other read or write support, use
 :py:func:`PIL.WmfImagePlugin.register_handler` to register a WMF and EMF
-handler.
-
-.. code-block:: python
+handler. ::
 
     from PIL import Image
     from PIL import WmfImagePlugin

docs/handbook/text-anchors.rst

@@ -29,7 +29,7 @@ For example, in the following image, the text is ``ms`` (middle-baseline) aligne
   :alt: ms (middle-baseline) aligned text.
   :align: left
 
-.. code-block:: python
+::
 
     from PIL import Image, ImageDraw, ImageFont
 

docs/handbook/writing-your-own-image-plugin.rst

@@ -108,9 +108,7 @@ Note that the image plugin must be explicitly registered using
 :py:func:`PIL.Image.register_open`. Although not required, it is also a good
 idea to register any extensions used by this format.
 
-Once the plugin has been imported, it can be used:
-
-.. code-block:: python
+Once the plugin has been imported, it can be used::
 
     from PIL import Image
     import SpamImagePlugin
@@ -169,9 +167,7 @@ The raw decoder
 The ``raw`` decoder is used to read uncompressed data from an image file. It
 can be used with most uncompressed file formats, such as PPM, BMP, uncompressed
 TIFF, and many others. To use the raw decoder with the
-:py:func:`PIL.Image.frombytes` function, use the following syntax:
-
-.. code-block:: python
+:py:func:`PIL.Image.frombytes` function, use the following syntax::
 
     image = Image.frombytes(
         mode, size, data, "raw",
@@ -281,9 +277,7 @@ decoder that can be used to read various packed formats into a floating point
 image memory.
 
 To use the bit decoder with the :py:func:`PIL.Image.frombytes` function, use
-the following syntax:
-
-.. code-block:: python
+the following syntax::
 
     image = Image.frombytes(
         mode, size, data, "bit",

docs/reference/Image.rst

@@ -17,9 +17,7 @@ Open, rotate, and display an image (using the default viewer)
 
 The following script loads an image, rotates it 45 degrees, and displays it
 using an external viewer (usually xv on Unix, and the Paint program on
-Windows).
-
-.. code-block:: python
+Windows). ::
 
     from PIL import Image
     with Image.open("hopper.jpg") as im:
@@ -29,9 +27,7 @@ Create thumbnails
 ^^^^^^^^^^^^^^^^^
 
 The following script creates nice thumbnails of all JPEG images in the
-current directory preserving aspect ratios with 128x128 max resolution.
-
-.. code-block:: python
+current directory preserving aspect ratios with 128x128 max resolution. ::
 
     from PIL import Image
     import glob, os
@@ -127,9 +123,7 @@ methods. Unless otherwise stated, all methods return a new instance of the
 .. automethod:: PIL.Image.Image.convert
 
 The following example converts an RGB image (linearly calibrated according to
-ITU-R 709, using the D65 luminant) to the CIE XYZ color space:
-
-.. code-block:: python
+ITU-R 709, using the D65 luminant) to the CIE XYZ color space::
 
     rgb2xyz = (
         0.412453, 0.357580, 0.180423, 0,
@@ -140,9 +134,7 @@ ITU-R 709, using the D65 luminant) to the CIE XYZ color space:
 .. automethod:: PIL.Image.Image.copy
 .. automethod:: PIL.Image.Image.crop
 
-This crops the input image with the provided coordinates:
-
-.. code-block:: python
+This crops the input image with the provided coordinates::
 
     from PIL import Image
 
@@ -162,9 +154,7 @@ This crops the input image with the provided coordinates:
 .. automethod:: PIL.Image.Image.entropy
 .. automethod:: PIL.Image.Image.filter
 
-This blurs the input image using a filter from the ``ImageFilter`` module:
-
-.. code-block:: python
+This blurs the input image using a filter from the ``ImageFilter`` module::
 
     from PIL import Image, ImageFilter
 
@@ -176,9 +166,7 @@ This blurs the input image using a filter from the ``ImageFilter`` module:
 .. automethod:: PIL.Image.Image.frombytes
 .. automethod:: PIL.Image.Image.getbands
 
-This helps to get the bands of the input image:
-
-.. code-block:: python
+This helps to get the bands of the input image::
 
     from PIL import Image
 
@@ -187,9 +175,7 @@ This helps to get the bands of the input image:
 
 .. automethod:: PIL.Image.Image.getbbox
 
-This helps to get the bounding box coordinates of the input image:
-
-.. code-block:: python
+This helps to get the bounding box coordinates of the input image::
 
     from PIL import Image
 
@@ -217,9 +203,7 @@ This helps to get the bounding box coordinates of the input image:
 .. automethod:: PIL.Image.Image.remap_palette
 .. automethod:: PIL.Image.Image.resize
 
-This resizes the given image from ``(width, height)`` to ``(width/2, height/2)``:
-
-.. code-block:: python
+This resizes the given image from ``(width, height)`` to ``(width/2, height/2)``::
 
     from PIL import Image
 
@@ -231,9 +215,7 @@ This resizes the given image from ``(width, height)`` to ``(width/2, height/2)``
 
 .. automethod:: PIL.Image.Image.rotate
 
-This rotates the input image by ``theta`` degrees counter clockwise:
-
-.. code-block:: python
+This rotates the input image by ``theta`` degrees counter clockwise::
 
     from PIL import Image
 
@@ -256,9 +238,7 @@ This rotates the input image by ``theta`` degrees counter clockwise:
 .. automethod:: PIL.Image.Image.transpose
 
 This flips the input image by using the :data:`Transpose.FLIP_LEFT_RIGHT`
-method.
-
-.. code-block:: python
+method. ::
 
     from PIL import Image
 

docs/reference/ImageDraw.rst

@@ -16,7 +16,7 @@ For a more advanced drawing library for PIL, see the `aggdraw module`_.
 Example: Draw a gray cross over an image
 ----------------------------------------
 
-.. code-block:: python
+::
 
     import sys
     from PIL import Image, ImageDraw
@@ -78,7 +78,7 @@ libraries, and may not available in all PIL builds.
 Example: Draw Partial Opacity Text
 ----------------------------------
 
-.. code-block:: python
+::
 
     from PIL import Image, ImageDraw, ImageFont
 
@@ -105,7 +105,7 @@ Example: Draw Partial Opacity Text
 Example: Draw Multiline Text
 ----------------------------
 
-.. code-block:: python
+::
 
     from PIL import Image, ImageDraw, ImageFont
 
@@ -597,18 +597,14 @@ Methods
     string due to kerning. If you need to adjust for kerning, include the following
     character and subtract its length.
 
-    For example, instead of
-
-    .. code-block:: python
+    For example, instead of ::
 
         hello = draw.textlength("Hello", font)
         world = draw.textlength("World", font)
         hello_world = hello + world  # not adjusted for kerning
         assert hello_world == draw.textlength("HelloWorld", font)  # may fail
 
-    use
-
-    .. code-block:: python
+    use ::
 
         hello = draw.textlength("HelloW", font) - draw.textlength(
             "W", font
@@ -617,9 +613,7 @@ Methods
         hello_world = hello + world  # adjusted for kerning
         assert hello_world == draw.textlength("HelloWorld", font)  # True
 
-    or disable kerning with (requires libraqm)
-
-    .. code-block:: python
+    or disable kerning with (requires libraqm) ::
 
         hello = draw.textlength("Hello", font, features=["-kern"])
         world = draw.textlength("World", font, features=["-kern"])

docs/reference/ImageEnhance.rst

@@ -10,7 +10,7 @@ for image enhancement.
 Example: Vary the sharpness of an image
 ---------------------------------------
 
-.. code-block:: python
+::
 
     from PIL import ImageEnhance
 

docs/reference/ImageFile.rst

@@ -15,7 +15,7 @@ and **xmllib** modules.
 Example: Parse an image
 -----------------------
 
-.. code-block:: python
+::
 
     from PIL import ImageFile
 

docs/reference/ImageFilter.rst

@@ -11,7 +11,7 @@ filters, which can be be used with the :py:meth:`Image.filter()
 Example: Filter an image
 ------------------------
 
-.. code-block:: python
+::
 
     from PIL import ImageFilter
 

docs/reference/ImageFont.rst

@@ -21,7 +21,7 @@ the imToolkit package.
 Example
 -------
 
-.. code-block:: python
+::
 
     from PIL import ImageFont, ImageDraw
 

docs/reference/ImageMath.rst

@@ -11,7 +11,7 @@ an expression string and one or more images.
 Example: Using the :py:mod:`~PIL.ImageMath` module
 --------------------------------------------------
 
-.. code-block:: python
+::
 
     from PIL import Image, ImageMath
 

docs/reference/ImagePath.rst

@@ -60,9 +60,7 @@ vector data. Path objects can be passed to the methods on the
 .. py:method:: PIL.ImagePath.Path.transform(matrix)
 
     Transforms the path in place, using an affine transform. The matrix is a
-    6-tuple (a, b, c, d, e, f), and each point is mapped as follows:
-
-    .. code-block:: python
+    6-tuple (a, b, c, d, e, f), and each point is mapped as follows::
 
         xOut = xIn * a + yIn * b + c
         yOut = xIn * d + yIn * e + f

docs/reference/ImageSequence.rst

@@ -10,7 +10,7 @@ iterate over the frames of an image sequence.
 Extracting frames from an animation
 -----------------------------------
 
-.. code-block:: python
+::
 
     from PIL import Image, ImageSequence
 

docs/reference/ImageWin.rst

@@ -9,9 +9,7 @@ Windows.
 
 ImageWin can be used with PythonWin and other user interface toolkits that
 provide access to Windows device contexts or window handles. For example,
-Tkinter makes the window handle available via the winfo_id method:
-
-.. code-block:: python
+Tkinter makes the window handle available via the winfo_id method::
 
     from PIL import ImageWin
 

docs/reference/PixelAccess.rst

@@ -18,9 +18,7 @@ Example
 -------
 
 The following script loads an image, accesses one pixel from it, then
-changes it.
-
-.. code-block:: python
+changes it. ::
 
     from PIL import Image
 
@@ -35,9 +33,7 @@ Results in the following::
     (23, 24, 68)
     (0, 0, 0)
 
-Access using negative indexes is also possible.
-
-.. code-block:: python
+Access using negative indexes is also possible. ::
 
     px[-1, -1] = (0, 0, 0)
     print(px[-1, -1])

docs/reference/PyAccess.rst

@@ -17,9 +17,7 @@ The :py:mod:`~PIL.PyAccess` module provides a CFFI/Python implementation of the
 Example
 -------
 
-The following script loads an image, accesses one pixel from it, then changes it.
-
-.. code-block:: python
+The following script loads an image, accesses one pixel from it, then changes it. ::
 
     from PIL import Image
 
@@ -34,9 +32,7 @@ Results in the following::
     (23, 24, 68)
     (0, 0, 0)
 
-Access using negative indexes is also possible.
-
-.. code-block:: python
+Access using negative indexes is also possible. ::
 
     px[-1, -1] = (0, 0, 0)
     print(px[-1, -1])

docs/reference/open_files.rst

@@ -61,9 +61,7 @@ Image Lifecycle
 * ``Image.Image.close()`` Closes the file and destroys the core image object.
 
   The Pillow context manager will also close the file, but will not destroy
-  the core image object. e.g.:
-
-.. code-block:: python
+  the core image object. e.g.::
 
     with Image.open("test.jpg") as img:
         img.load()

docs/releasenotes/6.1.0.rst

@@ -13,16 +13,12 @@ Implicitly closing the image's underlying file in ``Image.__del__`` has been dep
 Use a context manager or call ``Image.close()`` instead to close the file in a
 deterministic way.
 
-Deprecated:
-
-.. code-block:: python
+Deprecated::
 
     im = Image.open("hopper.png")
     im.save("out.jpg")
 
-Use instead:
-
-.. code-block:: python
+Use instead::
 
     with Image.open("hopper.png") as im:
         im.save("out.jpg")
@@ -79,9 +75,7 @@ Image quality for JPEG compressed TIFF
 
 The TIFF encoder accepts a ``quality`` parameter for ``jpeg`` compressed TIFF files. A
 value from 0 (worst) to 100 (best) controls the image quality, similar to the JPEG
-encoder. The default is 75. For example:
-
-.. code-block:: python
+encoder. The default is 75. For example::
 
     im.save("out.tif", compression="jpeg", quality=85)
 

docs/releasenotes/6.2.0.rst

@@ -10,9 +10,7 @@ Text stroking
 ``stroke_width`` and ``stroke_fill`` arguments have been added to text drawing
 operations. They allow text to be outlined, setting the width of the stroke and
 and the color respectively. If not provided, ``stroke_fill`` will default to
-the ``fill`` parameter.
-
-.. code-block:: python
+the ``fill`` parameter. ::
 
     from PIL import Image, ImageDraw, ImageFont
 
@@ -28,9 +26,7 @@ the ``fill`` parameter.
     draw.multiline_text((10, 10), "A\nB", "#f00", font,
                         stroke_width=2, stroke_fill="#0f0")
 
-For example,
-
-.. code-block:: python
+For example, ::
 
     from PIL import Image, ImageDraw, ImageFont
 

docs/releasenotes/7.0.0.rst

@@ -118,9 +118,7 @@ Loading WMF images at a given DPI
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 On Windows, Pillow can read WMF files, with a default DPI of 72. An image can
-now also be loaded at another resolution:
-
-.. code-block:: python
+now also be loaded at another resolution::
 
     from PIL import Image
     with Image.open("drawing.wmf") as im:
@@ -136,16 +134,12 @@ Implicitly closing the image's underlying file in ``Image.__del__`` has been rem
 Use a context manager or call :py:meth:`~PIL.Image.Image.close` instead to close
 the file in a deterministic way.
 
-Previous method:
-
-.. code-block:: python
+Previous method::
 
     im = Image.open("hopper.png")
     im.save("out.jpg")
 
-Use instead:
-
-.. code-block:: python
+Use instead::
 
     with Image.open("hopper.png") as im:
         im.save("out.jpg")

docs/releasenotes/7.1.0.rst

@@ -10,9 +10,7 @@ Allow saving of zero quality JPEG images
 If no quality was specified when saving a JPEG, Pillow internally used a value
 of zero to indicate that the default quality should be used. However, this
 removed the ability to actually save a JPEG with zero quality. This has now
-been resolved.
-
-.. code-block:: python
+been resolved. ::
 
     from PIL import Image
     im = Image.open("hopper.jpg")

docs/releasenotes/8.2.0.rst

@@ -76,9 +76,7 @@ ImageDraw.rounded_rectangle
 Added :py:meth:`~PIL.ImageDraw.ImageDraw.rounded_rectangle`. It works the same as
 :py:meth:`~PIL.ImageDraw.ImageDraw.rectangle`, except with an additional ``radius``
 argument. ``radius`` is limited to half of the width or the height, so that users can
-create a circle, but not any other ellipse.
-
-.. code-block:: python
+create a circle, but not any other ellipse. ::
 
     from PIL import Image, ImageDraw
     im = Image.new("RGB", (200, 200))

docs/releasenotes/8.4.0.rst

@@ -24,9 +24,7 @@ Added "transparency" argument for loading EPS images
 
 This new argument switches the Ghostscript device from "ppmraw" to "pngalpha",
 generating an RGBA image with a transparent background instead of an RGB image with a
-white background.
-
-.. code-block:: python
+white background. ::
 
     with Image.open("sample.eps") as im:
         im.load(transparency=True)

docs/releasenotes/9.0.0.rst

@@ -155,9 +155,7 @@ altered slightly with this change.
 Added support for pickling TrueType fonts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-TrueType fonts may now be pickled and unpickled. For example:
-
-.. code-block:: python
+TrueType fonts may now be pickled and unpickled. For example::
 
     import pickle
     from PIL import ImageFont

docs/releasenotes/9.1.0.rst

@@ -182,17 +182,13 @@ GifImagePlugin loading strategy
 
 Pillow 9.0.0 introduced the conversion of subsequent GIF frames to ``RGB`` or ``RGBA``. This
 behaviour can now be changed so that the first ``P`` frame is converted to ``RGB`` as
-well.
-
-.. code-block:: python
+well. ::
 
     from PIL import GifImagePlugin
     GifImagePlugin.LOADING_STRATEGY = GifImagePlugin.LoadingStrategy.RGB_ALWAYS
 
 Or subsequent frames can be kept in ``P`` mode as long as there is only a single
-palette.
-
-.. code-block:: python
+palette. ::
 
     from PIL import GifImagePlugin
     GifImagePlugin.LOADING_STRATEGY = GifImagePlugin.LoadingStrategy.RGB_AFTER_DIFFERENT_PALETTE_ONLY

docs/releasenotes/9.2.0.rst

@@ -59,9 +59,7 @@ Deprecated                                                                  Use
 :py:meth:`.ImageDraw2.Draw.textsize`                                        :py:meth:`.ImageDraw2.Draw.textbbox` and :py:meth:`.ImageDraw2.Draw.textlength`
 =========================================================================== =============================================================================================================
 
-Previous code:
-
-.. code-block:: python
+Previous code::
 
     from PIL import Image, ImageDraw, ImageFont
 
@@ -76,9 +74,7 @@ Previous code:
     width, height = font.getsize_multiline("Hello\nworld")
     width, height = draw.multiline_textsize("Hello\nworld")
 
-Use instead:
-
-.. code-block:: python
+Use instead::
 
     from PIL import Image, ImageDraw, ImageFont
 

src/PIL/ImageChops.py

@@ -38,9 +38,7 @@ def duplicate(image):
 
 def invert(image):
     """
-    Invert an image (channel).
-
-    .. code-block:: python
+    Invert an image (channel). ::
 
         out = MAX - image
 
@@ -54,9 +52,7 @@ def invert(image):
 def lighter(image1, image2):
     """
     Compares the two images, pixel by pixel, and returns a new image containing
-    the lighter values.
-
-    .. code-block:: python
+    the lighter values. ::
 
         out = max(image1, image2)
 
@@ -71,9 +67,7 @@ def lighter(image1, image2):
 def darker(image1, image2):
     """
     Compares the two images, pixel by pixel, and returns a new image containing
-    the darker values.
-
-    .. code-block:: python
+    the darker values. ::
 
         out = min(image1, image2)
 
@@ -88,9 +82,7 @@ def darker(image1, image2):
 def difference(image1, image2):
     """
     Returns the absolute value of the pixel-by-pixel difference between the two
-    images.
-
-    .. code-block:: python
+    images. ::
 
         out = abs(image1 - image2)
 
@@ -107,9 +99,7 @@ def multiply(image1, image2):
     Superimposes two images on top of each other.
 
     If you multiply an image with a solid black image, the result is black. If
-    you multiply with a solid white image, the image is unaffected.
-
-    .. code-block:: python
+    you multiply with a solid white image, the image is unaffected. ::
 
         out = image1 * image2 / MAX
 
@@ -123,9 +113,7 @@ def multiply(image1, image2):
 
 def screen(image1, image2):
     """
-    Superimposes two inverted images on top of each other.
-
-    .. code-block:: python
+    Superimposes two inverted images on top of each other. ::
 
         out = MAX - ((MAX - image1) * (MAX - image2) / MAX)
 
@@ -176,9 +164,7 @@ def overlay(image1, image2):
 def add(image1, image2, scale=1.0, offset=0):
     """
     Adds two images, dividing the result by scale and adding the
-    offset. If omitted, scale defaults to 1.0, and offset to 0.0.
-
-    .. code-block:: python
+    offset. If omitted, scale defaults to 1.0, and offset to 0.0. ::
 
         out = ((image1 + image2) / scale + offset)
 
@@ -193,9 +179,7 @@ def add(image1, image2, scale=1.0, offset=0):
 def subtract(image1, image2, scale=1.0, offset=0):
     """
     Subtracts two images, dividing the result by scale and adding the offset.
-    If omitted, scale defaults to 1.0, and offset to 0.0.
-
-    .. code-block:: python
+    If omitted, scale defaults to 1.0, and offset to 0.0. ::
 
         out = ((image1 - image2) / scale + offset)
 
@@ -208,9 +192,7 @@ def subtract(image1, image2, scale=1.0, offset=0):
 
 
 def add_modulo(image1, image2):
-    """Add two images, without clipping the result.
-
-    .. code-block:: python
+    """Add two images, without clipping the result. ::
 
         out = ((image1 + image2) % MAX)
 
@@ -223,9 +205,7 @@ def add_modulo(image1, image2):
 
 
 def subtract_modulo(image1, image2):
-    """Subtract two images, without clipping the result.
-
-    .. code-block:: python
+    """Subtract two images, without clipping the result. ::
 
         out = ((image1 - image2) % MAX)
 
@@ -243,9 +223,7 @@ def logical_and(image1, image2):
     Both of the images must have mode "1". If you would like to perform a
     logical AND on an image with a mode other than "1", try
     :py:meth:`~PIL.ImageChops.multiply` instead, using a black-and-white mask
-    as the second image.
-
-    .. code-block:: python
+    as the second image. ::
 
         out = ((image1 and image2) % MAX)
 
@@ -260,9 +238,7 @@ def logical_and(image1, image2):
 def logical_or(image1, image2):
     """Logical OR between two images.
 
-    Both of the images must have mode "1".
-
-    .. code-block:: python
+    Both of the images must have mode "1". ::
 
         out = ((image1 or image2) % MAX)
 
@@ -277,9 +253,7 @@ def logical_or(image1, image2):
 def logical_xor(image1, image2):
     """Logical XOR between two images.
 
-    Both of the images must have mode "1".
-
-    .. code-block:: python
+    Both of the images must have mode "1". ::
 
         out = ((bool(image1) != bool(image2)) % MAX)
 

src/PIL/ImageFont.py

@@ -297,27 +297,21 @@ class FreeTypeFont:
         string due to kerning. If you need to adjust for kerning, include the following
         character and subtract its length.
 
-        For example, instead of
-
-        .. code-block:: python
+        For example, instead of ::
 
           hello = font.getlength("Hello")
           world = font.getlength("World")
           hello_world = hello + world  # not adjusted for kerning
           assert hello_world == font.getlength("HelloWorld")  # may fail
 
-        use
-
-        .. code-block:: python
+        use ::
 
           hello = font.getlength("HelloW") - font.getlength("W")  # adjusted for kerning
           world = font.getlength("World")
           hello_world = hello + world  # adjusted for kerning
           assert hello_world == font.getlength("HelloWorld")  # True
 
-        or disable kerning with (requires libraqm)
-
-        .. code-block:: python
+        or disable kerning with (requires libraqm) ::
 
           hello = draw.textlength("Hello", font, features=["-kern"])
           world = draw.textlength("World", font, features=["-kern"])

winbuild/build.rst

@@ -96,9 +96,7 @@ directory.
 Example
 -------
 
-The following is a simplified version of the script used on AppVeyor:
-
-.. code-block::
+The following is a simplified version of the script used on AppVeyor::
 
     set PYTHON=C:\Python38\bin
     cd /D C:\Pillow\winbuild