From dc0c7bea375f3772b480e43faf3ab0174d5dd5e0 Mon Sep 17 00:00:00 2001 From: Hugo Date: Mon, 1 Jun 2020 10:16:30 +0300 Subject: [PATCH 1/6] Update ImageDraw docs formatting and links --- docs/reference/ImageDraw.rst | 72 ++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 3e453dd6f..967437568 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -81,13 +81,13 @@ Example: Draw Partial Opacity Text from PIL import Image, ImageDraw, ImageFont # get an image - base = Image.open('Pillow/Tests/images/hopper.png').convert('RGBA') + base = Image.open("Pillow/Tests/images/hopper.png").convert("RGBA") # make a blank image for the text, initialized to transparent text color - txt = Image.new('RGBA', base.size, (255,255,255,0)) + txt = Image.new("RGBA", base.size, (255,255,255,0)) # get a font - fnt = ImageFont.truetype('Pillow/Tests/fonts/FreeMono.ttf', 40) + fnt = ImageFont.truetype("Pillow/Tests/fonts/FreeMono.ttf", 40) # get a drawing context d = ImageDraw.Draw(txt) @@ -280,15 +280,15 @@ Methods :param xy: Top left corner of the text. :param text: Text to be drawn. If it contains any newline characters, - the text is passed on to multiline_text() + the text is passed on to ``multiline_text()`` :param fill: Color to use for the text. :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. - :param spacing: If the text is passed on to multiline_text(), + :param spacing: If the text is passed on to ``multiline_text()``, the number of pixels between lines. - :param align: If the text is passed on to multiline_text(), + :param align: If the text is passed on to ``multiline_text()``, "left", "center" or "right". - :param direction: Direction of the text. It can be 'rtl' (right to - left), 'ltr' (left to right) or 'ttb' (top to bottom). + :param direction: Direction of the text. It can be ``"rtl"`` (right to + left), ``"ltr"`` (left to right) or ``"ttb"`` (top to bottom). Requires libraqm. .. versionadded:: 4.2.0 @@ -296,9 +296,9 @@ Methods :param features: A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, - for example 'dlig' or 'ss01', but can be also - used to turn off default font features for - example '-liga' to disable ligatures or '-kern' + for example ``"dlig"`` or ``"ss01"``, but can be also + used to turn off default font features, for + example ``"-liga"`` to disable ligatures or ``"-kern"`` to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist @@ -310,8 +310,7 @@ Methods different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. - It should be a `BCP 47 language code - ` + It should be a `BCP 47 language code`_. Requires libraqm. .. versionadded:: 6.0.0 @@ -334,9 +333,9 @@ Methods :param fill: Color to use for the text. :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. :param spacing: The number of pixels between lines. - :param align: "left", "center" or "right". - :param direction: Direction of the text. It can be 'rtl' (right to - left), 'ltr' (left to right) or 'ttb' (top to bottom). + :param align: ``"left"``, ``"center"`` or ``"right"``. + :param direction: Direction of the text. It can be ``"rtl"`` (right to + left), ``"ltr"`` (left to right) or ``"ttb"`` (top to bottom). Requires libraqm. .. versionadded:: 4.2.0 @@ -344,9 +343,9 @@ Methods :param features: A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, - for example 'dlig' or 'ss01', but can be also - used to turn off default font features for - example '-liga' to disable ligatures or '-kern' + for example ``"dlig"`` or ``"ss01"``, but can be also + used to turn off default font features, for + example ``"-liga"`` to disable ligatures or ``"-kern"`` to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist @@ -358,8 +357,7 @@ Methods different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. - It should be a `BCP 47 language code - ` + It should be a `BCP 47 language code`_. Requires libraqm. .. versionadded:: 6.0.0 @@ -369,21 +367,21 @@ Methods Return the size of the given string, in pixels. :param text: Text to be measured. If it contains any newline characters, - the text is passed on to multiline_textsize() + the text is passed on to ``multiline_textsize()`` :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. - :param spacing: If the text is passed on to multiline_textsize(), + :param spacing: If the text is passed on to ``multiline_textsize()``, the number of pixels between lines. - :param direction: Direction of the text. It can be 'rtl' (right to - left), 'ltr' (left to right) or 'ttb' (top to bottom). + :param direction: Direction of the text. It can be ``"rtl"`` (right to + left), ``"ltr"`` (left to right) or ``"ttb"`` (top to bottom). Requires libraqm. .. versionadded:: 4.2.0 :param features: A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, - for example 'dlig' or 'ss01', but can be also - used to turn off default font features for - example '-liga' to disable ligatures or '-kern' + for example ``"dlig"`` or ``"ss01"``, but can be also + used to turn off default font features, for + example ``"-liga"`` to disable ligatures or ``"-kern"`` to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist @@ -394,8 +392,7 @@ Methods different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. - It should be a `BCP 47 language code - ` + It should be a `BCP 47 language code`_. Requires libraqm. .. versionadded:: 6.0.0 @@ -411,8 +408,8 @@ Methods :param text: Text to be measured. :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. :param spacing: The number of pixels between lines. - :param direction: Direction of the text. It can be 'rtl' (right to - left), 'ltr' (left to right) or 'ttb' (top to bottom). + :param direction: Direction of the text. It can be ``"rtl"`` (right to + left), ``"ltr"`` (left to right) or ``"ttb"`` (top to bottom). Requires libraqm. .. versionadded:: 4.2.0 @@ -420,9 +417,9 @@ Methods :param features: A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, - for example 'dlig' or 'ss01', but can be also - used to turn off default font features for - example '-liga' to disable ligatures or '-kern' + for example ``"dlig"`` or ``"ss01"``, but can be also + used to turn off default font features, for + example ``"-liga"`` to disable ligatures or ``"-kern"`` to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist @@ -434,8 +431,7 @@ Methods different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. - It should be a `BCP 47 language code - ` + It should be a `BCP 47 language code`_. Requires libraqm. .. versionadded:: 6.0.0 @@ -472,3 +468,5 @@ Methods tolerable difference of a pixel value from the 'background' in order for it to be replaced. Useful for filling regions of non- homogeneous, but similar, colors. + +.. _BCP 47 language code: https://www.w3.org/International/articles/language-tags/ From 087e42f7432e5cb697de569ad64b5ca3f778b93d Mon Sep 17 00:00:00 2001 From: Hugo Date: Tue, 2 Jun 2020 21:28:34 +0300 Subject: [PATCH 2/6] Move OpenType docs link to a reference --- docs/reference/ImageDraw.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 967437568..7bfe884a0 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -300,8 +300,7 @@ Methods used to turn off default font features, for example ``"-liga"`` to disable ligatures or ``"-kern"`` to disable kerning. To get all supported - features, see - https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist + features, see `OpenType docs`_. Requires libraqm. .. versionadded:: 4.2.0 @@ -347,8 +346,7 @@ Methods used to turn off default font features, for example ``"-liga"`` to disable ligatures or ``"-kern"`` to disable kerning. To get all supported - features, see - https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist + features, see `OpenType docs`_. Requires libraqm. .. versionadded:: 4.2.0 @@ -383,8 +381,7 @@ Methods used to turn off default font features, for example ``"-liga"`` to disable ligatures or ``"-kern"`` to disable kerning. To get all supported - features, see - https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist + features, see `OpenType docs`_. Requires libraqm. .. versionadded:: 4.2.0 @@ -421,8 +418,7 @@ Methods used to turn off default font features, for example ``"-liga"`` to disable ligatures or ``"-kern"`` to disable kerning. To get all supported - features, see - https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist + features, see `OpenType docs`_. Requires libraqm. .. versionadded:: 4.2.0 @@ -470,3 +466,4 @@ Methods homogeneous, but similar, colors. .. _BCP 47 language code: https://www.w3.org/International/articles/language-tags/ +.. _OpenType docs: https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist From 87de783226f5efa9d1b437dee79e49ec9de2ce93 Mon Sep 17 00:00:00 2001 From: Hugo Date: Tue, 2 Jun 2020 21:48:53 +0300 Subject: [PATCH 3/6] Replace simple code formatting with :py:meth: markup --- docs/reference/ImageDraw.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 7bfe884a0..ff65f88aa 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -280,12 +280,15 @@ Methods :param xy: Top left corner of the text. :param text: Text to be drawn. If it contains any newline characters, - the text is passed on to ``multiline_text()`` + the text is passed on to + :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_text` :param fill: Color to use for the text. :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. - :param spacing: If the text is passed on to ``multiline_text()``, + :param spacing: If the text is passed on to + :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_text`, the number of pixels between lines. - :param align: If the text is passed on to ``multiline_text()``, + :param align: If the text is passed on to + :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_text`, "left", "center" or "right". :param direction: Direction of the text. It can be ``"rtl"`` (right to left), ``"ltr"`` (left to right) or ``"ttb"`` (top to bottom). @@ -365,9 +368,10 @@ Methods Return the size of the given string, in pixels. :param text: Text to be measured. If it contains any newline characters, - the text is passed on to ``multiline_textsize()`` + the text is passed on to :py:meth:`~PIL.ImageDraw.ImageDraw.size` :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. - :param spacing: If the text is passed on to ``multiline_textsize()``, + :param spacing: If the text is passed on to + :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_textsize`, the number of pixels between lines. :param direction: Direction of the text. It can be ``"rtl"`` (right to left), ``"ltr"`` (left to right) or ``"ttb"`` (top to bottom). From 14302aa53d73d55b4bfcc32a68b5898dd7bffe50 Mon Sep 17 00:00:00 2001 From: Hugo Date: Tue, 2 Jun 2020 22:14:36 +0300 Subject: [PATCH 4/6] Fix parameter formatting --- docs/reference/ImageDraw.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index ff65f88aa..6f1d093f9 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -212,8 +212,8 @@ Methods .. versionadded:: 1.1.5 .. note:: This option was broken until version 1.1.6. - :param joint: Joint type between a sequence of lines. It can be "curve", - for rounded edges, or None. + :param joint: Joint type between a sequence of lines. It can be "curve", for rounded + edges, or ``None``. .. versionadded:: 5.3.0 @@ -281,7 +281,7 @@ Methods :param xy: Top left corner of the text. :param text: Text to be drawn. If it contains any newline characters, the text is passed on to - :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_text` + :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_text`. :param fill: Color to use for the text. :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. :param spacing: If the text is passed on to @@ -322,9 +322,9 @@ Methods .. versionadded:: 6.2.0 :param stroke_fill: Color to use for the text stroke. If not given, will default to - the ``fill`` parameter. + the ``fill`` parameter. - .. versionadded:: 6.2.0 + .. versionadded:: 6.2.0 .. py:method:: PIL.ImageDraw.ImageDraw.multiline_text(xy, text, fill=None, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None) @@ -368,7 +368,7 @@ Methods Return the size of the given string, in pixels. :param text: Text to be measured. If it contains any newline characters, - the text is passed on to :py:meth:`~PIL.ImageDraw.ImageDraw.size` + the text is passed on to :py:meth:`~PIL.ImageDraw.ImageDraw.size`. :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. :param spacing: If the text is passed on to :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_textsize`, From 95f3f359b7a0fa34a1490fa74f0e8bd881e2e392 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 3 Jun 2020 11:23:24 +0300 Subject: [PATCH 5/6] Fix name Co-authored-by: Andrew Murray <3112309+radarhere@users.noreply.github.com> --- docs/reference/ImageDraw.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 6f1d093f9..adfb46bcf 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -368,7 +368,7 @@ Methods Return the size of the given string, in pixels. :param text: Text to be measured. If it contains any newline characters, - the text is passed on to :py:meth:`~PIL.ImageDraw.ImageDraw.size`. + the text is passed on to :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_textsize`. :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. :param spacing: If the text is passed on to :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_textsize`, From cda682efc41a56bfef25b681edf5a0d0c713ac73 Mon Sep 17 00:00:00 2001 From: Hugo Date: Thu, 4 Jun 2020 11:43:24 +0300 Subject: [PATCH 6/6] Parameter values in code formatting --- docs/reference/ImageDraw.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index adfb46bcf..1a0dd3b68 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -212,8 +212,8 @@ Methods .. versionadded:: 1.1.5 .. note:: This option was broken until version 1.1.6. - :param joint: Joint type between a sequence of lines. It can be "curve", for rounded - edges, or ``None``. + :param joint: Joint type between a sequence of lines. It can be ``"curve"``, + for rounded edges, or ``None``. .. versionadded:: 5.3.0 @@ -289,7 +289,7 @@ Methods the number of pixels between lines. :param align: If the text is passed on to :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_text`, - "left", "center" or "right". + ``"left"``, ``"center"`` or ``"right"``. :param direction: Direction of the text. It can be ``"rtl"`` (right to left), ``"ltr"`` (left to right) or ``"ttb"`` (top to bottom). Requires libraqm.