Merge pull request #7016 from hugovk/docs-replace-sphinx-issues

radarhere · web-flow · commit 770084024022 · 2023-03-22T16:24:53.000+11:00
Docs: Replace dependency sphinx-issues with builtin sphinx.ext.extlinks
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -18,6 +18,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  FORCE_COLOR: 1
+
 jobs:
   build:
 
diff --git a/Makefile b/Makefile
@@ -16,10 +16,16 @@ coverage:
 	python3 -m coverage report
 
 .PHONY: doc
-doc:
+.PHONY: html
+doc html:
 	python3 -c "import PIL" > /dev/null 2>&1 || python3 -m pip install .
 	$(MAKE) -C docs html
 
+.PHONY: htmlview
+htmlview:
+	python3 -c "import PIL" > /dev/null 2>&1 || python3 -m pip install .
+	$(MAKE) -C docs htmlview
+
 .PHONY: doccheck
 doccheck:
 	$(MAKE) doc
@@ -38,7 +44,8 @@ help:
 	@echo "  coverage           run coverage test (in progress)"
 	@echo "  doc                make HTML docs"
 	@echo "  docserve           run an HTTP server on the docs directory"
-	@echo "  html               to make standalone HTML files"
+	@echo "  html               make HTML docs"
+	@echo "  htmlview           open the index page built by the html target in your browser"
 	@echo "  inplace            make inplace extension"
 	@echo "  install            make and install"
 	@echo "  install-coverage   make and install with C coverage"
diff --git a/docs/Makefile b/docs/Makefile
@@ -19,6 +19,7 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
+	@echo "  htmlview   to open the index page built by the html target in your browser"
 	@echo "  serve      to start a local server for viewing docs"
 	@echo "  livehtml   to start a local server for viewing docs and auto-reload on change"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
@@ -45,7 +46,7 @@ clean:
 	-rm -rf $(BUILDDIR)/*
 
 install-sphinx:
-	$(PYTHON) -m pip install --quiet furo olefile sphinx sphinx-copybutton sphinx-inline-tabs sphinx-issues sphinx-removed-in sphinxext-opengraph
+	$(PYTHON) -m pip install --quiet furo olefile sphinx sphinx-copybutton sphinx-inline-tabs sphinx-removed-in sphinxext-opengraph
 
 .PHONY: html
 html:
@@ -196,6 +197,10 @@ doctest:
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
+.PHONY: htmlview
+htmlview: html
+	$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('$(BUILDDIR)/html/index.html'))"
+
 .PHONY: livehtml
 livehtml: html
 	livereload $(BUILDDIR)/html -p 33233
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,11 +28,11 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
     "sphinx_inline_tabs",
-    "sphinx_issues",
     "sphinx_removed_in",
     "sphinxext.opengraph",
 ]
@@ -317,8 +317,17 @@ def setup(app):
     app.add_css_file("css/dark.css")
 
 
-# GitHub repo for sphinx-issues
-issues_github_path = "python-pillow/Pillow"
+# sphinx.ext.extlinks
+# This config is a dictionary of external sites,
+# mapping unique short aliases to a base URL and a prefix.
+# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
+_repo = "https://github.com/python-pillow/Pillow/"
+extlinks = {
+    "cve": ("https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s", "CVE-%s"),
+    "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
+    "issue": (_repo + "issues/%s", "#%s"),
+    "pr": (_repo + "pull/%s", "#%s"),
+}
 
 # sphinxext.opengraph
 ogp_image = (
diff --git a/docs/deprecations.rst b/docs/deprecations.rst
@@ -261,7 +261,7 @@ FreeType 2.7
 Support for FreeType 2.7 has been removed.
 
 We recommend upgrading to at least `FreeType`_ 2.10.4, which fixed a severe
-vulnerability introduced in FreeType 2.6 (:cve:`CVE-2020-15999`).
+vulnerability introduced in FreeType 2.6 (:cve:`2020-15999`).
 
 .. _FreeType: https://freetype.org/
 
diff --git a/docs/make.bat b/docs/make.bat
@@ -19,6 +19,7 @@ if "%1" == "help" (
 	:help
 	echo.Please use `make ^<target^>` where ^<target^> is one of
 	echo.  html       to make standalone HTML files
+	echo.  htmlview   to open the index page built by the html target in your browser
 	echo.  dirhtml    to make HTML files named index.html in directories
 	echo.  singlehtml to make a single large HTML file
 	echo.  pickle     to make pickle files
@@ -44,12 +45,23 @@ if "%1" == "clean" (
 	goto end
 )
 
-if "%1" == "html" (
+set html=false
+if "%1%" == "html" set html=true
+if "%1%" == "htmlview" set html=true
+if "%html%" == "true" (
 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
+
+    if "%1" == "htmlview" (
+        if EXIST "%BUILDDIR%\html\index.html" (
+            echo.Opening "%BUILDDIR%\html\index.html" in the default web browser...
+            start "" "%BUILDDIR%\html\index.html"
+        )
+    )
+
+    goto end
 )
 
 if "%1" == "dirhtml" (
diff --git a/docs/releasenotes/3.1.1.rst b/docs/releasenotes/3.1.1.rst
@@ -6,7 +6,7 @@ CVE-2016-0740 -- Buffer overflow in TiffDecode.c
 ------------------------------------------------
 
 Pillow 3.1.0 and earlier when linked against libtiff >= 4.0.0 on x64
-may overflow a buffer when reading a specially crafted tiff file (:cve:`CVE-2016-0740`).
+may overflow a buffer when reading a specially crafted tiff file (:cve:`2016-0740`).
 
 Specifically, libtiff >= 4.0.0 changed the return type of
 ``TIFFScanlineSize`` from ``int32`` to machine dependent
@@ -24,7 +24,7 @@ CVE-2016-0775 -- Buffer overflow in FliDecode.c
 -----------------------------------------------
 
 In all versions of Pillow, dating back at least to the last PIL 1.1.7
-release, FliDecode.c has a buffer overflow error (:cve:`CVE-2016-0775`).
+release, FliDecode.c has a buffer overflow error (:cve:`2016-0775`).
 
 Around line 192:
 
@@ -53,7 +53,7 @@ CVE-2016-2533 -- Buffer overflow in PcdDecode.c
 -----------------------------------------------
 
 In all versions of Pillow, dating back at least to the last PIL 1.1.7
-release, ``PcdDecode.c`` has a buffer overflow error (:cve:`CVE-2016-2533`).
+release, ``PcdDecode.c`` has a buffer overflow error (:cve:`2016-2533`).
 
 The ``state.buffer`` for ``PcdDecode.c`` is allocated based on a 3
 bytes per pixel sizing, where ``PcdDecode.c`` wrote into the buffer
diff --git a/docs/releasenotes/3.1.2.rst b/docs/releasenotes/3.1.2.rst
@@ -7,7 +7,7 @@ CVE-2016-3076 -- Buffer overflow in Jpeg2KEncode.c
 
 Pillow between 2.5.0 and 3.1.1 may overflow a buffer when writing
 large Jpeg2000 files, allowing for code execution or other memory
-corruption (:cve:`CVE-2016-3076`).
+corruption (:cve:`2016-3076`).
 
 This occurs specifically in the function ``j2k_encode_entry``, at the line:
 
diff --git a/docs/releasenotes/6.2.0.rst b/docs/releasenotes/6.2.0.rst
@@ -69,7 +69,7 @@ Security
 ========
 
 This release catches several buffer overruns, as well as addressing
-:cve:`CVE-2019-16865`. The CVE is regarding DOS problems, such as consuming large
+:cve:`2019-16865`. The CVE is regarding DOS problems, such as consuming large
 amounts of memory, or taking a large amount of time to process an image.
 
 In RawDecode.c, an error is now thrown if skip is calculated to be less than
diff --git a/docs/releasenotes/6.2.2.rst b/docs/releasenotes/6.2.2.rst
@@ -6,13 +6,13 @@ Security
 
 This release addresses several security problems.
 
-:cve:`CVE-2019-19911` is regarding FPX images. If an image reports that it has a large
+:cve:`2019-19911` is regarding FPX images. If an image reports that it has a large
 number of bands, a large amount of resources will be used when trying to process the
 image. This is fixed by limiting the number of bands to those usable by Pillow.
 
-Buffer overruns were found when processing an SGI (:cve:`CVE-2020-5311`),
-PCX (:cve:`CVE-2020-5312`) or FLI image (:cve:`CVE-2020-5313`). Checks have been added
+Buffer overruns were found when processing an SGI (:cve:`2020-5311`),
+PCX (:cve:`2020-5312`) or FLI image (:cve:`2020-5313`). Checks have been added
 to prevent this.
 
-:cve:`CVE-2020-5310`: Overflow checks have been added when calculating the size of a
+:cve:`2020-5310`: Overflow checks have been added when calculating the size of a
 memory block to be reallocated in the processing of a TIFF image.
diff --git a/docs/releasenotes/7.1.0.rst b/docs/releasenotes/7.1.0.rst
@@ -72,11 +72,11 @@ Security
 
 This release includes security fixes.
 
-* :cve:`CVE-2020-10177` Fix multiple out-of-bounds reads in FLI decoding
-* :cve:`CVE-2020-10378` Fix bounds overflow in PCX decoding
-* :cve:`CVE-2020-10379` Fix two buffer overflows in TIFF decoding
-* :cve:`CVE-2020-10994` Fix bounds overflow in JPEG 2000 decoding
-* :cve:`CVE-2020-11538` Fix buffer overflow in SGI-RLE decoding
+* :cve:`2020-10177` Fix multiple out-of-bounds reads in FLI decoding
+* :cve:`2020-10378` Fix bounds overflow in PCX decoding
+* :cve:`2020-10379` Fix two buffer overflows in TIFF decoding
+* :cve:`2020-10994` Fix bounds overflow in JPEG 2000 decoding
+* :cve:`2020-11538` Fix buffer overflow in SGI-RLE decoding
 
 Other Changes
 =============
diff --git a/docs/releasenotes/8.0.1.rst b/docs/releasenotes/8.0.1.rst
@@ -4,7 +4,7 @@
 Security
 ========
 
-Update FreeType used in binary wheels to `2.10.4`_ to fix :cve:`CVE-2020-15999`:
+Update FreeType used in binary wheels to `2.10.4`_ to fix :cve:`2020-15999`:
 
   - A heap buffer overflow has been found  in the handling of embedded PNG bitmaps,
     introduced in FreeType version 2.6.
diff --git a/docs/releasenotes/8.1.0.rst b/docs/releasenotes/8.1.0.rst
@@ -11,7 +11,7 @@ Support for FreeType 2.7 is deprecated and will be removed in Pillow 9.0.0 (2022
 when FreeType 2.8 will be the minimum supported.
 
 We recommend upgrading to at least FreeType `2.10.4`_, which fixed a severe
-vulnerability introduced in FreeType 2.6 (:cve:`CVE-2020-15999`).
+vulnerability introduced in FreeType 2.6 (:cve:`2020-15999`).
 
 .. _2.10.4: https://sourceforge.net/projects/freetype/files/freetype2/2.10.4/
 
@@ -40,13 +40,13 @@ This release includes security fixes.
 
 * An out-of-bounds read when saving TIFFs with custom metadata through LibTIFF
 * An out-of-bounds read when saving a GIF of 1px width
-* :cve:`CVE-2020-35653` Buffer read overrun in PCX decoding
+* :cve:`2020-35653` Buffer read overrun in PCX decoding
 
 The PCX image decoder used the reported image stride to calculate the row buffer,
 rather than calculating it from the image size. This issue dates back to the PIL fork.
 Thanks to Google's `OSS-Fuzz`_ project for finding this.
 
-* :cve:`CVE-2020-35654` Fix TIFF out-of-bounds write error
+* :cve:`2020-35654` Fix TIFF out-of-bounds write error
 
 Out-of-bounds write in ``TiffDecode.c`` when reading corrupt YCbCr files in some
 LibTIFF versions (4.1.0/Ubuntu 20.04, but not 4.0.9/Ubuntu 18.04). In some cases
@@ -55,7 +55,7 @@ an out-of-bounds write in ``TiffDecode.c``. This potentially affects Pillow vers
 from 6.0.0 to 8.0.1, depending on the version of LibTIFF. This was reported through
 `Tidelift`_.
 
-* :cve:`CVE-2020-35655` Fix for SGI Decode buffer overrun
+* :cve:`2020-35655` Fix for SGI Decode buffer overrun
 
 4 byte read overflow in ``SgiRleDecode.c``, where the code was not correctly checking the
 offsets and length tables. Independently reported through `Tidelift`_ and Google's
diff --git a/docs/releasenotes/8.1.1.rst b/docs/releasenotes/8.1.1.rst
@@ -4,19 +4,19 @@
 Security
 ========
 
-:cve:`CVE-2021-25289`: The previous fix for :cve:`CVE-2020-35654` was insufficient
+:cve:`2021-25289`: The previous fix for :cve:`2020-35654` was insufficient
 due to incorrect error checking in ``TiffDecode.c``.
 
-:cve:`CVE-2021-25290`: In ``TiffDecode.c``, there is a negative-offset ``memcpy``
+:cve:`2021-25290`: In ``TiffDecode.c``, there is a negative-offset ``memcpy``
 with an invalid size.
 
-:cve:`CVE-2021-25291`: In ``TiffDecode.c``, invalid tile boundaries could lead to
+:cve:`2021-25291`: In ``TiffDecode.c``, invalid tile boundaries could lead to
 an out-of-bounds read in ``TIFFReadRGBATile``.
 
-:cve:`CVE-2021-25292`: The PDF parser has a catastrophic backtracking regex
+:cve:`2021-25292`: The PDF parser has a catastrophic backtracking regex
 that could be used as a DOS attack.
 
-:cve:`CVE-2021-25293`: There is an out-of-bounds read in ``SgiRleDecode.c``,
+:cve:`2021-25293`: There is an out-of-bounds read in ``SgiRleDecode.c``,
 since Pillow 4.3.0.
 
 
diff --git a/docs/releasenotes/8.1.2.rst b/docs/releasenotes/8.1.2.rst
@@ -4,8 +4,8 @@
 Security
 ========
 
-There is an exhaustion of memory DOS in the BLP (:cve:`CVE-2021-27921`),
-ICNS (:cve:`CVE-2021-27922`) and ICO (:cve:`CVE-2021-27923`) container formats
+There is an exhaustion of memory DOS in the BLP (:cve:`2021-27921`),
+ICNS (:cve:`2021-27922`) and ICO (:cve:`2021-27923`) container formats
 where Pillow did not properly check the reported size of the contained image.
 These images could cause arbitrarily large memory allocations. This was reported
 by Jiayi Lin, Luke Shaffer, Xinran Xie, and Akshay Ajayan of
diff --git a/docs/releasenotes/8.2.0.rst b/docs/releasenotes/8.2.0.rst
@@ -129,31 +129,31 @@ Security
 
 These were all found with `OSS-Fuzz`_.
 
-:cve:`CVE-2021-25287`, :cve:`CVE-2021-25288`: Fix OOB read in Jpeg2KDecode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:cve:`2021-25287`, :cve:`2021-25288`: Fix OOB read in Jpeg2KDecode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * For J2k images with multiple bands, it's legal to have different widths for each band,
   e.g. 1 byte for ``L``, 4 bytes for ``A``.
 * This dates to Pillow 2.4.0.
 
-:cve:`CVE-2021-28675`: Fix DOS in PsdImagePlugin
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:cve:`2021-28675`: Fix DOS in PsdImagePlugin
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * :py:class:`.PsdImagePlugin.PsdImageFile` did not sanity check the number of input
   layers with regard to the size of the data block, this could lead to a
   denial-of-service on :py:meth:`~PIL.Image.open` prior to
   :py:meth:`~PIL.Image.Image.load`.
 * This dates to the PIL fork.
 
-:cve:`CVE-2021-28676`: Fix FLI DOS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:cve:`2021-28676`: Fix FLI DOS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * ``FliDecode.c`` did not properly check that the block advance was non-zero,
   potentially leading to an infinite loop on load.
 * This dates to the PIL fork.
 
-:cve:`CVE-2021-28677`: Fix EPS DOS on _open
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:cve:`2021-28677`: Fix EPS DOS on _open
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * The readline used in EPS has to deal with any combination of ``\r`` and ``\n`` as line
   endings. It accidentally used a quadratic method of accumulating lines while looking
@@ -162,8 +162,8 @@ These were all found with `OSS-Fuzz`_.
   open phase, before an image was accepted for opening.
 * This dates to the PIL fork.
 
-:cve:`CVE-2021-28678`: Fix BLP DOS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:cve:`2021-28678`: Fix BLP DOS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * ``BlpImagePlugin`` did not properly check that reads after jumping to file offsets
   returned data. This could lead to a denial-of-service where the decoder could be run a
diff --git a/docs/releasenotes/8.3.0.rst b/docs/releasenotes/8.3.0.rst
@@ -85,7 +85,7 @@ Security
 Buffer overflow
 ^^^^^^^^^^^^^^^
 
-This release addresses :cve:`CVE-2021-34552`. PIL since 1.1.4 and Pillow since 1.0
+This release addresses :cve:`2021-34552`. PIL since 1.1.4 and Pillow since 1.0
 allowed parameters passed into a convert function to trigger buffer overflow in
 Convert.c.
 
diff --git a/docs/releasenotes/8.3.2.rst b/docs/releasenotes/8.3.2.rst
@@ -4,7 +4,7 @@
 Security
 ========
 
-* :cve:`CVE-2021-23437`: Avoid a potential ReDoS (regular expression denial of service)
+* :cve:`2021-23437`: Avoid a potential ReDoS (regular expression denial of service)
   in :py:class:`~PIL.ImageColor`'s :py:meth:`~PIL.ImageColor.getrgb` by raising
   :py:exc:`ValueError` if the color specifier is too long. Present since Pillow 5.2.0.
 
diff --git a/docs/releasenotes/9.0.0.rst b/docs/releasenotes/9.0.0.rst
@@ -43,7 +43,7 @@ FreeType 2.7
 Support for FreeType 2.7 has been removed; FreeType 2.8 is the minimum supported.
 
 We recommend upgrading to at least `FreeType`_ 2.10.4, which fixed a severe
-vulnerability introduced in FreeType 2.6 (:cve:`CVE-2020-15999`).
+vulnerability introduced in FreeType 2.6 (:cve:`2020-15999`).
 
 .. _FreeType: https://freetype.org/
 
@@ -119,15 +119,15 @@ Google's `OSS-Fuzz`_ project for finding this issue.
 Restrict builtins available to ImageMath.eval
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-:cve:`CVE-2022-22817`: To limit :py:class:`PIL.ImageMath` to working with images, Pillow
+:cve:`2022-22817`: To limit :py:class:`PIL.ImageMath` to working with images, Pillow
 will now restrict the builtins available to :py:meth:`PIL.ImageMath.eval`. This will
 help prevent problems arising if users evaluate arbitrary expressions, such as
 ``ImageMath.eval("exec(exit())")``.
 
 Fixed ImagePath.Path array handling
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-:cve:`CVE-2022-22815` (:cwe:`CWE-126`) and :cve:`CVE-2022-22816` (:cwe:`CWE-665`) were
+:cve:`2022-22815` (:cwe:`126`) and :cve:`2022-22816` (:cwe:`665`) were
 found when initializing ``ImagePath.Path``.
 
 .. _OSS-Fuzz: https://github.com/google/oss-fuzz
diff --git a/docs/releasenotes/9.0.1.rst b/docs/releasenotes/9.0.1.rst
diff --git a/docs/releasenotes/9.1.1.rst b/docs/releasenotes/9.1.1.rst
diff --git a/setup.cfg b/setup.cfg
