Merge pull request #4773 from nulano/refs-png

docs/PIL.rst

@@ -93,8 +93,8 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:class:`PngImagePlugin.iTXt` Class
+:class:`.PngImagePlugin.iTXt` Class
-----------------------------------
+-----------------------------------
 
 .. autoclass:: PIL.PngImagePlugin.iTXt
     :members:
@@ -107,8 +107,8 @@ can be found here.
         :param lang: language code
         :param tkey: UTF-8 version of the key name
 
-:class:`PngImagePlugin.PngInfo` Class
+:class:`.PngImagePlugin.PngInfo` Class
--------------------------------------
+--------------------------------------
 
 .. autoclass:: PIL.PngImagePlugin.PngInfo
     :members:

docs/handbook/image-file-formats.rst

@@ -501,12 +501,14 @@ The :py:meth:`~PIL.Image.Image.open` method sets the following
 
     This key is omitted if the image is not a transparent palette image.
 
+.. _png-text:
+
 ``open`` also sets ``Image.text`` to a dictionary of the values of the
 ``tEXt``, ``zTXt``, and ``iTXt`` chunks of the PNG image. Individual
 compressed chunks are limited to a decompressed size of
-``PngImagePlugin.MAX_TEXT_CHUNK``, by default 1MB, to prevent
+:data:`.PngImagePlugin.MAX_TEXT_CHUNK`, by default 1MB, to prevent
 decompression bombs. Additionally, the total size of all of the text
-chunks is limited to ``PngImagePlugin.MAX_TEXT_MEMORY``, defaulting to
+chunks is limited to :data:`.PngImagePlugin.MAX_TEXT_MEMORY`, defaulting to
 64MB.
 
 The :py:meth:`~PIL.Image.Image.save` method supports the following options:
@@ -611,6 +613,8 @@ where applicable:
     Any APNG file containing sequence errors is treated as an invalid image. The APNG
     loader will not attempt to repair and reorder files containing sequence errors.
 
+.. _apng-saving:
+
 Saving
 ~~~~~~
 

docs/reference/plugins.rst

@@ -229,20 +229,12 @@ Plugin reference
 ---------------------------------
 
 .. automodule:: PIL.PngImagePlugin
-    :members: ChunkStream, PngStream, getchunks, is_cid, putchunk
+    :members: ChunkStream, PngImageFile, PngStream, getchunks, is_cid, putchunk,
-    :show-inheritance:
+        MAX_TEXT_CHUNK, MAX_TEXT_MEMORY, APNG_BLEND_OP_SOURCE, APNG_BLEND_OP_OVER,
-.. autoclass:: PIL.PngImagePlugin.ChunkStream
+        APNG_DISPOSE_OP_NONE, APNG_DISPOSE_OP_BACKGROUND, APNG_DISPOSE_OP_PREVIOUS
-    :members:
-    :undoc-members:
-    :show-inheritance:
-.. autoclass:: PIL.PngImagePlugin.PngImageFile
-    :members:
-    :undoc-members:
-    :show-inheritance:
-.. autoclass:: PIL.PngImagePlugin.PngStream
-    :members:
     :undoc-members:
     :show-inheritance:
+    :member-order: groupwise
 
 
 :mod:`~PIL.PpmImagePlugin` Module

src/PIL/PngImagePlugin.py

@@ -76,21 +76,50 @@ _MODES = {
 
 _simple_palette = re.compile(b"^\xff*\x00\xff*$")
 
-# Maximum decompressed size for a iTXt or zTXt chunk.
-# Eliminates decompression bombs where compressed chunks can expand 1000x
 MAX_TEXT_CHUNK = ImageFile.SAFEBLOCK
-# Set the maximum total text chunk size.
+"""
+Maximum decompressed size for a iTXt or zTXt chunk.
+Eliminates decompression bombs where compressed chunks can expand 1000x.
+See :ref:`Text in PNG File Format<png-text>`.
+"""
 MAX_TEXT_MEMORY = 64 * MAX_TEXT_CHUNK
+"""
+Set the maximum total text chunk size.
+See :ref:`Text in PNG File Format<png-text>`.
+"""
 
 
 # APNG frame disposal modes
 APNG_DISPOSE_OP_NONE = 0
+"""
+No disposal is done on this frame before rendering the next frame.
+See :ref:`Saving APNG sequences<apng-saving>`.
+"""
 APNG_DISPOSE_OP_BACKGROUND = 1
+"""
+This frame’s modified region is cleared to fully transparent black before rendering
+the next frame.
+See :ref:`Saving APNG sequences<apng-saving>`.
+"""
 APNG_DISPOSE_OP_PREVIOUS = 2
+"""
+This frame’s modified region is reverted to the previous frame’s contents before
+rendering the next frame.
+See :ref:`Saving APNG sequences<apng-saving>`.
+"""
 
 # APNG frame blend modes
 APNG_BLEND_OP_SOURCE = 0
+"""
+All color components of this frame, including alpha, overwrite the previous output
+image contents.
+See :ref:`Saving APNG sequences<apng-saving>`.
+"""
 APNG_BLEND_OP_OVER = 1
+"""
+This frame should be alpha composited with the previous output image contents.
+See :ref:`Saving APNG sequences<apng-saving>`.
+"""
 
 
 def _safe_zlib_decompress(s):