From e3a46fcfd0111d7f080da0efe5846430771afeeb Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 28 Nov 2022 11:08:39 +0200 Subject: [PATCH 1/8] Use sphinx-inline-tabs to organise installation per OS --- .editorconfig | 4 + docs/Makefile | 2 +- docs/conf.py | 7 +- docs/installation.rst | 263 +++++++++++++++++++++--------------------- setup.cfg | 1 + 5 files changed, 142 insertions(+), 135 deletions(-) diff --git a/.editorconfig b/.editorconfig index d74549fe2ac..7f5eab05673 100644 --- a/.editorconfig +++ b/.editorconfig @@ -13,6 +13,10 @@ indent_style = space trim_trailing_whitespace = true +[*.rst] +# Three-space indentation +indent_size = 3 + [*.yml] # Two-space indentation indent_size = 2 diff --git a/docs/Makefile b/docs/Makefile index 458299aac7b..0a663ce2b0c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -43,7 +43,7 @@ clean: -rm -rf $(BUILDDIR)/* install-sphinx: - $(PYTHON) -m pip install --quiet sphinx sphinx-copybutton sphinx-issues sphinx-removed-in sphinxext-opengraph furo olefile + $(PYTHON) -m pip install --quiet furo olefile sphinx sphinx-copybutton sphinx-inline-tabs sphinx-issues sphinx-removed-in sphinxext-opengraph html: $(MAKE) install-sphinx diff --git a/docs/conf.py b/docs/conf.py index bc67d936893..04823e2d7c7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,12 +27,13 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - "sphinx_copybutton", - "sphinx_issues", - "sphinx_removed_in", "sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.viewcode", + "sphinx_copybutton", + "sphinx_inline_tabs", + "sphinx_issues", + "sphinx_removed_in", "sphinxext.opengraph", ] diff --git a/docs/installation.rst b/docs/installation.rst index 6d67a253656..3c86f09cc27 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -23,6 +23,11 @@ Pillow supports these Python versions. :file: older-versions.csv :header-rows: 1 +.. _Windows Installation: +.. _macOS Installation: +.. _Linux Installation: +.. _FreeBSD Installation: + Basic Installation ------------------ @@ -38,67 +43,69 @@ Install Pillow with :command:`pip`:: python3 -m pip install --upgrade Pillow -Windows Installation -^^^^^^^^^^^^^^^^^^^^ +.. tab:: Windows -We provide Pillow binaries for Windows compiled for the matrix of -supported Pythons in both 32 and 64-bit versions in the wheel format. -These binaries include support for all optional libraries except -libimagequant and libxcb. Raqm support requires -FriBiDi to be installed separately:: + We provide Pillow binaries for Windows compiled for the matrix of + supported Pythons in both 32 and 64-bit versions in the wheel format. + These binaries include support for all optional libraries except + libimagequant and libxcb. Raqm support requires + FriBiDi to be installed separately:: - python3 -m pip install --upgrade pip - python3 -m pip install --upgrade Pillow + python3 -m pip install --upgrade pip + python3 -m pip install --upgrade Pillow -To install Pillow in MSYS2, see `Building on Windows using MSYS2/MinGW`_. + To install Pillow in MSYS2, see `Building on Windows using MSYS2/MinGW`_. +.. tab:: macOS -macOS Installation -^^^^^^^^^^^^^^^^^^ + We provide binaries for macOS for each of the supported Python + versions in the wheel format. These include support for all optional + libraries except libimagequant. Raqm support requires + FriBiDi to be installed separately:: -We provide binaries for macOS for each of the supported Python -versions in the wheel format. These include support for all optional -libraries except libimagequant. Raqm support requires -FriBiDi to be installed separately:: + python3 -m pip install --upgrade pip + python3 -m pip install --upgrade Pillow - python3 -m pip install --upgrade pip - python3 -m pip install --upgrade Pillow +.. tab:: Linux -Linux Installation -^^^^^^^^^^^^^^^^^^ + We provide binaries for Linux for each of the supported Python + versions in the manylinux wheel format. These include support for all + optional libraries except libimagequant. Raqm support requires + FriBiDi to be installed separately:: -We provide binaries for Linux for each of the supported Python -versions in the manylinux wheel format. These include support for all -optional libraries except libimagequant. Raqm support requires -FriBiDi to be installed separately:: + python3 -m pip install --upgrade pip + python3 -m pip install --upgrade Pillow - python3 -m pip install --upgrade pip - python3 -m pip install --upgrade Pillow + Most major Linux distributions, including Fedora, Ubuntu and ArchLinux + also include Pillow in packages that previously contained PIL e.g. + ``python-imaging``. Debian splits it into two packages, ``python3-pil`` + and ``python3-pil.imagetk``. -Most major Linux distributions, including Fedora, Ubuntu and ArchLinux -also include Pillow in packages that previously contained PIL e.g. -``python-imaging``. Debian splits it into two packages, ``python3-pil`` -and ``python3-pil.imagetk``. +.. tab:: FreeBSD -FreeBSD Installation -^^^^^^^^^^^^^^^^^^^^ + Pillow can be installed on FreeBSD via the official Ports or Packages systems: -Pillow can be installed on FreeBSD via the official Ports or Packages systems: + **Ports**:: -**Ports**:: + cd /usr/ports/graphics/py-pillow && make install clean - cd /usr/ports/graphics/py-pillow && make install clean + **Packages**:: -**Packages**:: + pkg install py38-pillow - pkg install py38-pillow + .. note:: -.. note:: + The `Pillow FreeBSD port + `_ and packages + are tested by the ports team with all supported FreeBSD versions. - The `Pillow FreeBSD port - `_ and packages - are tested by the ports team with all supported FreeBSD versions. +.. _Building on macOS: +.. _Building on Windows: +.. _Building on Windows using MSYS2/MinGW: +.. _Building on FreeBSD: +.. _Building on Linux: +.. _Building on Android: Building From Source -------------------- @@ -187,141 +194,135 @@ Many of Pillow's features require external libraries: * **libxcb** provides X11 screengrab support. -Building on macOS -""""""""""""""""" +.. tab:: macOS -The Xcode command line tools are required to compile portions of -Pillow. The tools are installed by running ``xcode-select --install`` -from the command line. The command line tools are required even if you -have the full Xcode package installed. It may be necessary to run -``sudo xcodebuild -license`` to accept the license prior to using the -tools. + The Xcode command line tools are required to compile portions of + Pillow. The tools are installed by running ``xcode-select --install`` + from the command line. The command line tools are required even if you + have the full Xcode package installed. It may be necessary to run + ``sudo xcodebuild -license`` to accept the license prior to using the + tools. -The easiest way to install external libraries is via `Homebrew -`_. After you install Homebrew, run:: + The easiest way to install external libraries is via `Homebrew + `_. After you install Homebrew, run:: - brew install libjpeg libtiff little-cms2 openjpeg webp + brew install libjpeg libtiff little-cms2 openjpeg webp -To install libraqm on macOS use Homebrew to install its dependencies:: + To install libraqm on macOS use Homebrew to install its dependencies:: - brew install freetype harfbuzz fribidi + brew install freetype harfbuzz fribidi -Then see ``depends/install_raqm_cmake.sh`` to install libraqm. + Then see ``depends/install_raqm_cmake.sh`` to install libraqm. -Building on Windows -""""""""""""""""""" +.. tab:: Windows -We recommend you use prebuilt wheels from PyPI. -If you wish to compile Pillow manually, you can use the build scripts -in the ``winbuild`` directory used for CI testing and development. -These scripts require Visual Studio 2017 or newer and NASM. + We recommend you use prebuilt wheels from PyPI. + If you wish to compile Pillow manually, you can use the build scripts + in the ``winbuild`` directory used for CI testing and development. + These scripts require Visual Studio 2017 or newer and NASM. -The scripts also install Pillow from the local copy of the source code, so the -`Installing`_ instructions will not be necessary afterwards. + The scripts also install Pillow from the local copy of the source code, so the + `Installing`_ instructions will not be necessary afterwards. -Building on Windows using MSYS2/MinGW -""""""""""""""""""""""""""""""""""""" +.. tab:: Windows using MSYS2/MinGW -To build Pillow using MSYS2, make sure you run the **MSYS2 MinGW 32-bit** or -**MSYS2 MinGW 64-bit** console, *not* **MSYS2** directly. + To build Pillow using MSYS2, make sure you run the **MSYS2 MinGW 32-bit** or + **MSYS2 MinGW 64-bit** console, *not* **MSYS2** directly. -The following instructions target the 64-bit build, for 32-bit -replace all occurrences of ``mingw-w64-x86_64-`` with ``mingw-w64-i686-``. + The following instructions target the 64-bit build, for 32-bit + replace all occurrences of ``mingw-w64-x86_64-`` with ``mingw-w64-i686-``. -Make sure you have Python and GCC installed:: + Make sure you have Python and GCC installed:: - pacman -S \ - mingw-w64-x86_64-gcc \ - mingw-w64-x86_64-python3 \ - mingw-w64-x86_64-python3-pip \ - mingw-w64-x86_64-python3-setuptools + pacman -S \ + mingw-w64-x86_64-gcc \ + mingw-w64-x86_64-python3 \ + mingw-w64-x86_64-python3-pip \ + mingw-w64-x86_64-python3-setuptools -Prerequisites are installed on **MSYS2 MinGW 64-bit** with:: + Prerequisites are installed on **MSYS2 MinGW 64-bit** with:: - pacman -S \ - mingw-w64-x86_64-libjpeg-turbo \ - mingw-w64-x86_64-zlib \ - mingw-w64-x86_64-libtiff \ - mingw-w64-x86_64-freetype \ - mingw-w64-x86_64-lcms2 \ - mingw-w64-x86_64-libwebp \ - mingw-w64-x86_64-openjpeg2 \ - mingw-w64-x86_64-libimagequant \ - mingw-w64-x86_64-libraqm + pacman -S \ + mingw-w64-x86_64-libjpeg-turbo \ + mingw-w64-x86_64-zlib \ + mingw-w64-x86_64-libtiff \ + mingw-w64-x86_64-freetype \ + mingw-w64-x86_64-lcms2 \ + mingw-w64-x86_64-libwebp \ + mingw-w64-x86_64-openjpeg2 \ + mingw-w64-x86_64-libimagequant \ + mingw-w64-x86_64-libraqm -Building on FreeBSD -""""""""""""""""""" +.. tab:: FreeBSD -.. Note:: Only FreeBSD 10 and 11 tested + .. Note:: Only FreeBSD 10 and 11 tested -Make sure you have Python's development libraries installed:: + Make sure you have Python's development libraries installed:: - sudo pkg install python3 + sudo pkg install python3 -Prerequisites are installed on **FreeBSD 10 or 11** with:: + Prerequisites are installed on **FreeBSD 10 or 11** with:: - sudo pkg install jpeg-turbo tiff webp lcms2 freetype2 openjpeg harfbuzz fribidi libxcb + sudo pkg install jpeg-turbo tiff webp lcms2 freetype2 openjpeg harfbuzz fribidi libxcb -Then see ``depends/install_raqm_cmake.sh`` to install libraqm. + Then see ``depends/install_raqm_cmake.sh`` to install libraqm. -Building on Linux -""""""""""""""""" +.. tab:: Linux -If you didn't build Python from source, make sure you have Python's -development libraries installed. + If you didn't build Python from source, make sure you have Python's + development libraries installed. -In Debian or Ubuntu:: + In Debian or Ubuntu:: - sudo apt-get install python3-dev python3-setuptools + sudo apt-get install python3-dev python3-setuptools -In Fedora, the command is:: + In Fedora, the command is:: - sudo dnf install python3-devel redhat-rpm-config + sudo dnf install python3-devel redhat-rpm-config -In Alpine, the command is:: + In Alpine, the command is:: - sudo apk add python3-dev py3-setuptools + sudo apk add python3-dev py3-setuptools -.. Note:: ``redhat-rpm-config`` is required on Fedora 23, but not earlier versions. + .. Note:: ``redhat-rpm-config`` is required on Fedora 23, but not earlier versions. -Prerequisites for **Ubuntu 16.04 LTS - 22.04 LTS** are installed with:: + Prerequisites for **Ubuntu 16.04 LTS - 22.04 LTS** are installed with:: - sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \ - libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \ - libharfbuzz-dev libfribidi-dev libxcb1-dev + sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \ + libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \ + libharfbuzz-dev libfribidi-dev libxcb1-dev -To install libraqm, ``sudo apt-get install meson`` and then see -``depends/install_raqm.sh``. + To install libraqm, ``sudo apt-get install meson`` and then see + ``depends/install_raqm.sh``. -Prerequisites are installed on recent **Red Hat**, **CentOS** or **Fedora** with:: + Prerequisites are installed on recent **Red Hat**, **CentOS** or **Fedora** with:: - sudo dnf install libtiff-devel libjpeg-devel openjpeg2-devel zlib-devel \ - freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel \ - harfbuzz-devel fribidi-devel libraqm-devel libimagequant-devel libxcb-devel + sudo dnf install libtiff-devel libjpeg-devel openjpeg2-devel zlib-devel \ + freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel \ + harfbuzz-devel fribidi-devel libraqm-devel libimagequant-devel libxcb-devel -Note that the package manager may be yum or DNF, depending on the -exact distribution. + Note that the package manager may be yum or DNF, depending on the + exact distribution. -Prerequisites are installed for **Alpine** with:: + Prerequisites are installed for **Alpine** with:: - sudo apk add tiff-dev jpeg-dev openjpeg-dev zlib-dev freetype-dev lcms2-dev \ - libwebp-dev tcl-dev tk-dev harfbuzz-dev fribidi-dev libimagequant-dev \ - libxcb-dev libpng-dev + sudo apk add tiff-dev jpeg-dev openjpeg-dev zlib-dev freetype-dev lcms2-dev \ + libwebp-dev tcl-dev tk-dev harfbuzz-dev fribidi-dev libimagequant-dev \ + libxcb-dev libpng-dev -See also the ``Dockerfile``\s in the Test Infrastructure repo -(https://github.com/python-pillow/docker-images) for a known working -install process for other tested distros. + See also the ``Dockerfile``\s in the Test Infrastructure repo + (https://github.com/python-pillow/docker-images) for a known working + install process for other tested distros. -Building on Android -""""""""""""""""""" +.. tab:: Android -Basic Android support has been added for compilation within the Termux -environment. The dependencies can be installed by:: + Basic Android support has been added for compilation within the Termux + environment. The dependencies can be installed by:: - pkg install -y python ndk-sysroot clang make \ - libjpeg-turbo + pkg install -y python ndk-sysroot clang make \ + libjpeg-turbo -This has been tested within the Termux app on ChromeOS, on x86. + This has been tested within the Termux app on ChromeOS, on x86. Installing ^^^^^^^^^^ diff --git a/setup.cfg b/setup.cfg index 44feb25ff7f..b562e293471 100644 --- a/setup.cfg +++ b/setup.cfg @@ -46,6 +46,7 @@ docs = olefile sphinx>=2.4 sphinx-copybutton + sphinx-inline-tabs sphinx-issues>=3.0.1 sphinx-removed-in sphinxext-opengraph From e6e5a0018e27779827678552ea2b17a7c1034e7e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 28 Nov 2022 12:34:43 +0200 Subject: [PATCH 2/8] Add missing 'make help' for serve and livehtml --- docs/Makefile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/Makefile b/docs/Makefile index 0a663ce2b0c..a65e2d3f58e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,6 +20,8 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" + @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" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @@ -38,6 +40,8 @@ help: @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @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" clean: -rm -rf $(BUILDDIR)/* From d12c119ec41e62642157a2add640fc0211d46066 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 28 Nov 2022 12:36:04 +0200 Subject: [PATCH 3/8] Inline PHONY targets to help avoid omissions (texinfo, info, livehtml, serve were missing) --- docs/Makefile | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index a65e2d3f58e..d5242f93510 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -15,8 +15,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - +.PHONY: help help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @@ -40,45 +39,50 @@ help: @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @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" +.PHONY: clean 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 +.PHONY: html html: $(MAKE) install-sphinx $(SPHINXBUILD) -b html -W --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +.PHONY: dirhtml dirhtml: $(MAKE) install-sphinx $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." +.PHONY: singlehtml singlehtml: $(MAKE) install-sphinx $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." +.PHONY: pickle pickle: $(MAKE) install-sphinx $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." +.PHONY: json json: $(MAKE) install-sphinx $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." +.PHONY: htmlhelp htmlhelp: $(MAKE) install-sphinx $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @@ -86,6 +90,7 @@ htmlhelp: @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." +.PHONY: qthelp qthelp: $(MAKE) install-sphinx $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @@ -96,6 +101,7 @@ qthelp: @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PillowPILfork.qhc" +.PHONY: devhelp devhelp: $(MAKE) install-sphinx $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @@ -106,12 +112,14 @@ devhelp: @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PillowPILfork" @echo "# devhelp" +.PHONY: epub epub: $(MAKE) install-sphinx $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." +.PHONY: latex latex: $(MAKE) install-sphinx $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @@ -120,6 +128,7 @@ latex: @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." +.PHONY: latexpdf latexpdf: $(MAKE) install-sphinx $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @@ -127,18 +136,21 @@ latexpdf: $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." +.PHONY: text text: $(MAKE) install-sphinx $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." +.PHONY: man man: $(MAKE) install-sphinx $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." +.PHONY: texinfo texinfo: $(MAKE) install-sphinx $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @@ -147,6 +159,7 @@ texinfo: @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." +.PHONY: info info: $(MAKE) install-sphinx $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @@ -154,18 +167,21 @@ info: make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." +.PHONY: gettext gettext: $(MAKE) install-sphinx $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." +.PHONY: changes changes: $(MAKE) install-sphinx $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." +.PHONY: linkcheck linkcheck: $(MAKE) install-sphinx $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck -j auto @@ -173,14 +189,17 @@ linkcheck: @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." +.PHONY: doctest doctest: $(MAKE) install-sphinx $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." +.PHONY: livehtml livehtml: html livereload $(BUILDDIR)/html -p 33233 +.PHONY: serve serve: cd $(BUILDDIR)/html; $(PYTHON) -m http.server From 5e42b1779e29ecbd34adcdd911b44cbe87ad439b Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 28 Nov 2022 12:50:55 +0200 Subject: [PATCH 4/8] Reorder tabs: big three OS first --- docs/installation.rst | 128 +++++++++++++++++++++--------------------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 3c86f09cc27..00924eab9b3 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -23,9 +23,9 @@ Pillow supports these Python versions. :file: older-versions.csv :header-rows: 1 -.. _Windows Installation: -.. _macOS Installation: .. _Linux Installation: +.. _macOS Installation: +.. _Windows Installation: .. _FreeBSD Installation: Basic Installation @@ -43,18 +43,20 @@ Install Pillow with :command:`pip`:: python3 -m pip install --upgrade Pillow -.. tab:: Windows +.. tab:: Linux - We provide Pillow binaries for Windows compiled for the matrix of - supported Pythons in both 32 and 64-bit versions in the wheel format. - These binaries include support for all optional libraries except - libimagequant and libxcb. Raqm support requires + We provide binaries for Linux for each of the supported Python + versions in the manylinux wheel format. These include support for all + optional libraries except libimagequant. Raqm support requires FriBiDi to be installed separately:: python3 -m pip install --upgrade pip python3 -m pip install --upgrade Pillow - To install Pillow in MSYS2, see `Building on Windows using MSYS2/MinGW`_. + Most major Linux distributions, including Fedora, Ubuntu and ArchLinux + also include Pillow in packages that previously contained PIL e.g. + ``python-imaging``. Debian splits it into two packages, ``python3-pil`` + and ``python3-pil.imagetk``. .. tab:: macOS @@ -66,20 +68,18 @@ Install Pillow with :command:`pip`:: python3 -m pip install --upgrade pip python3 -m pip install --upgrade Pillow -.. tab:: Linux +.. tab:: Windows - We provide binaries for Linux for each of the supported Python - versions in the manylinux wheel format. These include support for all - optional libraries except libimagequant. Raqm support requires + We provide Pillow binaries for Windows compiled for the matrix of + supported Pythons in both 32 and 64-bit versions in the wheel format. + These binaries include support for all optional libraries except + libimagequant and libxcb. Raqm support requires FriBiDi to be installed separately:: python3 -m pip install --upgrade pip python3 -m pip install --upgrade Pillow - Most major Linux distributions, including Fedora, Ubuntu and ArchLinux - also include Pillow in packages that previously contained PIL e.g. - ``python-imaging``. Debian splits it into two packages, ``python3-pil`` - and ``python3-pil.imagetk``. + To install Pillow in MSYS2, see `Building on Windows using MSYS2/MinGW`_. .. tab:: FreeBSD @@ -100,11 +100,11 @@ Install Pillow with :command:`pip`:: are tested by the ports team with all supported FreeBSD versions. +.. _Building on Linux: .. _Building on macOS: .. _Building on Windows: .. _Building on Windows using MSYS2/MinGW: .. _Building on FreeBSD: -.. _Building on Linux: .. _Building on Android: Building From Source @@ -194,6 +194,53 @@ Many of Pillow's features require external libraries: * **libxcb** provides X11 screengrab support. +.. tab:: Linux + + If you didn't build Python from source, make sure you have Python's + development libraries installed. + + In Debian or Ubuntu:: + + sudo apt-get install python3-dev python3-setuptools + + In Fedora, the command is:: + + sudo dnf install python3-devel redhat-rpm-config + + In Alpine, the command is:: + + sudo apk add python3-dev py3-setuptools + + .. Note:: ``redhat-rpm-config`` is required on Fedora 23, but not earlier versions. + + Prerequisites for **Ubuntu 16.04 LTS - 22.04 LTS** are installed with:: + + sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \ + libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \ + libharfbuzz-dev libfribidi-dev libxcb1-dev + + To install libraqm, ``sudo apt-get install meson`` and then see + ``depends/install_raqm.sh``. + + Prerequisites are installed on recent **Red Hat**, **CentOS** or **Fedora** with:: + + sudo dnf install libtiff-devel libjpeg-devel openjpeg2-devel zlib-devel \ + freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel \ + harfbuzz-devel fribidi-devel libraqm-devel libimagequant-devel libxcb-devel + + Note that the package manager may be yum or DNF, depending on the + exact distribution. + + Prerequisites are installed for **Alpine** with:: + + sudo apk add tiff-dev jpeg-dev openjpeg-dev zlib-dev freetype-dev lcms2-dev \ + libwebp-dev tcl-dev tk-dev harfbuzz-dev fribidi-dev libimagequant-dev \ + libxcb-dev libpng-dev + + See also the ``Dockerfile``\s in the Test Infrastructure repo + (https://github.com/python-pillow/docker-images) for a known working + install process for other tested distros. + .. tab:: macOS The Xcode command line tools are required to compile portions of @@ -267,53 +314,6 @@ Many of Pillow's features require external libraries: Then see ``depends/install_raqm_cmake.sh`` to install libraqm. -.. tab:: Linux - - If you didn't build Python from source, make sure you have Python's - development libraries installed. - - In Debian or Ubuntu:: - - sudo apt-get install python3-dev python3-setuptools - - In Fedora, the command is:: - - sudo dnf install python3-devel redhat-rpm-config - - In Alpine, the command is:: - - sudo apk add python3-dev py3-setuptools - - .. Note:: ``redhat-rpm-config`` is required on Fedora 23, but not earlier versions. - - Prerequisites for **Ubuntu 16.04 LTS - 22.04 LTS** are installed with:: - - sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \ - libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \ - libharfbuzz-dev libfribidi-dev libxcb1-dev - - To install libraqm, ``sudo apt-get install meson`` and then see - ``depends/install_raqm.sh``. - - Prerequisites are installed on recent **Red Hat**, **CentOS** or **Fedora** with:: - - sudo dnf install libtiff-devel libjpeg-devel openjpeg2-devel zlib-devel \ - freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel \ - harfbuzz-devel fribidi-devel libraqm-devel libimagequant-devel libxcb-devel - - Note that the package manager may be yum or DNF, depending on the - exact distribution. - - Prerequisites are installed for **Alpine** with:: - - sudo apk add tiff-dev jpeg-dev openjpeg-dev zlib-dev freetype-dev lcms2-dev \ - libwebp-dev tcl-dev tk-dev harfbuzz-dev fribidi-dev libimagequant-dev \ - libxcb-dev libpng-dev - - See also the ``Dockerfile``\s in the Test Infrastructure repo - (https://github.com/python-pillow/docker-images) for a known working - install process for other tested distros. - .. tab:: Android Basic Android support has been added for compilation within the Termux From 50ccb27a4d57500b9b5e474e276df03158b6c870 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 28 Nov 2022 23:23:46 +0200 Subject: [PATCH 5/8] Remove extra space Co-authored-by: Andrew Murray <3112309+radarhere@users.noreply.github.com> --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index d5242f93510..d32d25a3c49 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -90,7 +90,7 @@ htmlhelp: @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." -.PHONY: qthelp +.PHONY: qthelp qthelp: $(MAKE) install-sphinx $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp From 96b316880e284f4221b2d8400ef1bec5c81bcb83 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 2 Dec 2022 11:40:06 +0200 Subject: [PATCH 6/8] Use 4-space indents for RST --- .editorconfig | 2 +- docs/installation.rst | 218 +++++++++++++++++++++--------------------- 2 files changed, 110 insertions(+), 110 deletions(-) diff --git a/.editorconfig b/.editorconfig index 7f5eab05673..07f02c23665 100644 --- a/.editorconfig +++ b/.editorconfig @@ -15,7 +15,7 @@ trim_trailing_whitespace = true [*.rst] # Three-space indentation -indent_size = 3 +indent_size = 4 [*.yml] # Two-space indentation diff --git a/docs/installation.rst b/docs/installation.rst index 00924eab9b3..89b2e558f40 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -45,59 +45,59 @@ Install Pillow with :command:`pip`:: .. tab:: Linux - We provide binaries for Linux for each of the supported Python - versions in the manylinux wheel format. These include support for all - optional libraries except libimagequant. Raqm support requires - FriBiDi to be installed separately:: + We provide binaries for Linux for each of the supported Python + versions in the manylinux wheel format. These include support for all + optional libraries except libimagequant. Raqm support requires + FriBiDi to be installed separately:: - python3 -m pip install --upgrade pip - python3 -m pip install --upgrade Pillow + python3 -m pip install --upgrade pip + python3 -m pip install --upgrade Pillow - Most major Linux distributions, including Fedora, Ubuntu and ArchLinux - also include Pillow in packages that previously contained PIL e.g. - ``python-imaging``. Debian splits it into two packages, ``python3-pil`` - and ``python3-pil.imagetk``. + Most major Linux distributions, including Fedora, Ubuntu and ArchLinux + also include Pillow in packages that previously contained PIL e.g. + ``python-imaging``. Debian splits it into two packages, ``python3-pil`` + and ``python3-pil.imagetk``. .. tab:: macOS - We provide binaries for macOS for each of the supported Python - versions in the wheel format. These include support for all optional - libraries except libimagequant. Raqm support requires - FriBiDi to be installed separately:: + We provide binaries for macOS for each of the supported Python + versions in the wheel format. These include support for all optional + libraries except libimagequant. Raqm support requires + FriBiDi to be installed separately:: - python3 -m pip install --upgrade pip - python3 -m pip install --upgrade Pillow + python3 -m pip install --upgrade pip + python3 -m pip install --upgrade Pillow .. tab:: Windows - We provide Pillow binaries for Windows compiled for the matrix of - supported Pythons in both 32 and 64-bit versions in the wheel format. - These binaries include support for all optional libraries except - libimagequant and libxcb. Raqm support requires - FriBiDi to be installed separately:: + We provide Pillow binaries for Windows compiled for the matrix of + supported Pythons in both 32 and 64-bit versions in the wheel format. + These binaries include support for all optional libraries except + libimagequant and libxcb. Raqm support requires + FriBiDi to be installed separately:: - python3 -m pip install --upgrade pip - python3 -m pip install --upgrade Pillow + python3 -m pip install --upgrade pip + python3 -m pip install --upgrade Pillow - To install Pillow in MSYS2, see `Building on Windows using MSYS2/MinGW`_. + To install Pillow in MSYS2, see `Building on Windows using MSYS2/MinGW`_. .. tab:: FreeBSD - Pillow can be installed on FreeBSD via the official Ports or Packages systems: + Pillow can be installed on FreeBSD via the official Ports or Packages systems: - **Ports**:: + **Ports**:: - cd /usr/ports/graphics/py-pillow && make install clean + cd /usr/ports/graphics/py-pillow && make install clean - **Packages**:: + **Packages**:: - pkg install py38-pillow + pkg install py38-pillow - .. note:: + .. note:: - The `Pillow FreeBSD port - `_ and packages - are tested by the ports team with all supported FreeBSD versions. + The `Pillow FreeBSD port + `_ and packages + are tested by the ports team with all supported FreeBSD versions. .. _Building on Linux: @@ -196,133 +196,133 @@ Many of Pillow's features require external libraries: .. tab:: Linux - If you didn't build Python from source, make sure you have Python's - development libraries installed. + If you didn't build Python from source, make sure you have Python's + development libraries installed. - In Debian or Ubuntu:: + In Debian or Ubuntu:: - sudo apt-get install python3-dev python3-setuptools + sudo apt-get install python3-dev python3-setuptools - In Fedora, the command is:: + In Fedora, the command is:: sudo dnf install python3-devel redhat-rpm-config - In Alpine, the command is:: + In Alpine, the command is:: sudo apk add python3-dev py3-setuptools - .. Note:: ``redhat-rpm-config`` is required on Fedora 23, but not earlier versions. + .. Note:: ``redhat-rpm-config`` is required on Fedora 23, but not earlier versions. - Prerequisites for **Ubuntu 16.04 LTS - 22.04 LTS** are installed with:: + Prerequisites for **Ubuntu 16.04 LTS - 22.04 LTS** are installed with:: - sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \ - libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \ - libharfbuzz-dev libfribidi-dev libxcb1-dev + sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \ + libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \ + libharfbuzz-dev libfribidi-dev libxcb1-dev - To install libraqm, ``sudo apt-get install meson`` and then see - ``depends/install_raqm.sh``. + To install libraqm, ``sudo apt-get install meson`` and then see + ``depends/install_raqm.sh``. - Prerequisites are installed on recent **Red Hat**, **CentOS** or **Fedora** with:: + Prerequisites are installed on recent **Red Hat**, **CentOS** or **Fedora** with:: - sudo dnf install libtiff-devel libjpeg-devel openjpeg2-devel zlib-devel \ - freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel \ - harfbuzz-devel fribidi-devel libraqm-devel libimagequant-devel libxcb-devel + sudo dnf install libtiff-devel libjpeg-devel openjpeg2-devel zlib-devel \ + freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel \ + harfbuzz-devel fribidi-devel libraqm-devel libimagequant-devel libxcb-devel - Note that the package manager may be yum or DNF, depending on the - exact distribution. + Note that the package manager may be yum or DNF, depending on the + exact distribution. - Prerequisites are installed for **Alpine** with:: + Prerequisites are installed for **Alpine** with:: - sudo apk add tiff-dev jpeg-dev openjpeg-dev zlib-dev freetype-dev lcms2-dev \ - libwebp-dev tcl-dev tk-dev harfbuzz-dev fribidi-dev libimagequant-dev \ - libxcb-dev libpng-dev + sudo apk add tiff-dev jpeg-dev openjpeg-dev zlib-dev freetype-dev lcms2-dev \ + libwebp-dev tcl-dev tk-dev harfbuzz-dev fribidi-dev libimagequant-dev \ + libxcb-dev libpng-dev - See also the ``Dockerfile``\s in the Test Infrastructure repo - (https://github.com/python-pillow/docker-images) for a known working - install process for other tested distros. + See also the ``Dockerfile``\s in the Test Infrastructure repo + (https://github.com/python-pillow/docker-images) for a known working + install process for other tested distros. .. tab:: macOS - The Xcode command line tools are required to compile portions of - Pillow. The tools are installed by running ``xcode-select --install`` - from the command line. The command line tools are required even if you - have the full Xcode package installed. It may be necessary to run - ``sudo xcodebuild -license`` to accept the license prior to using the - tools. + The Xcode command line tools are required to compile portions of + Pillow. The tools are installed by running ``xcode-select --install`` + from the command line. The command line tools are required even if you + have the full Xcode package installed. It may be necessary to run + ``sudo xcodebuild -license`` to accept the license prior to using the + tools. - The easiest way to install external libraries is via `Homebrew - `_. After you install Homebrew, run:: + The easiest way to install external libraries is via `Homebrew + `_. After you install Homebrew, run:: - brew install libjpeg libtiff little-cms2 openjpeg webp + brew install libjpeg libtiff little-cms2 openjpeg webp - To install libraqm on macOS use Homebrew to install its dependencies:: + To install libraqm on macOS use Homebrew to install its dependencies:: - brew install freetype harfbuzz fribidi + brew install freetype harfbuzz fribidi - Then see ``depends/install_raqm_cmake.sh`` to install libraqm. + Then see ``depends/install_raqm_cmake.sh`` to install libraqm. .. tab:: Windows - We recommend you use prebuilt wheels from PyPI. - If you wish to compile Pillow manually, you can use the build scripts - in the ``winbuild`` directory used for CI testing and development. - These scripts require Visual Studio 2017 or newer and NASM. + We recommend you use prebuilt wheels from PyPI. + If you wish to compile Pillow manually, you can use the build scripts + in the ``winbuild`` directory used for CI testing and development. + These scripts require Visual Studio 2017 or newer and NASM. - The scripts also install Pillow from the local copy of the source code, so the - `Installing`_ instructions will not be necessary afterwards. + The scripts also install Pillow from the local copy of the source code, so the + `Installing`_ instructions will not be necessary afterwards. .. tab:: Windows using MSYS2/MinGW - To build Pillow using MSYS2, make sure you run the **MSYS2 MinGW 32-bit** or - **MSYS2 MinGW 64-bit** console, *not* **MSYS2** directly. + To build Pillow using MSYS2, make sure you run the **MSYS2 MinGW 32-bit** or + **MSYS2 MinGW 64-bit** console, *not* **MSYS2** directly. - The following instructions target the 64-bit build, for 32-bit - replace all occurrences of ``mingw-w64-x86_64-`` with ``mingw-w64-i686-``. + The following instructions target the 64-bit build, for 32-bit + replace all occurrences of ``mingw-w64-x86_64-`` with ``mingw-w64-i686-``. - Make sure you have Python and GCC installed:: + Make sure you have Python and GCC installed:: - pacman -S \ - mingw-w64-x86_64-gcc \ - mingw-w64-x86_64-python3 \ - mingw-w64-x86_64-python3-pip \ - mingw-w64-x86_64-python3-setuptools + pacman -S \ + mingw-w64-x86_64-gcc \ + mingw-w64-x86_64-python3 \ + mingw-w64-x86_64-python3-pip \ + mingw-w64-x86_64-python3-setuptools - Prerequisites are installed on **MSYS2 MinGW 64-bit** with:: + Prerequisites are installed on **MSYS2 MinGW 64-bit** with:: - pacman -S \ - mingw-w64-x86_64-libjpeg-turbo \ - mingw-w64-x86_64-zlib \ - mingw-w64-x86_64-libtiff \ - mingw-w64-x86_64-freetype \ - mingw-w64-x86_64-lcms2 \ - mingw-w64-x86_64-libwebp \ - mingw-w64-x86_64-openjpeg2 \ - mingw-w64-x86_64-libimagequant \ - mingw-w64-x86_64-libraqm + pacman -S \ + mingw-w64-x86_64-libjpeg-turbo \ + mingw-w64-x86_64-zlib \ + mingw-w64-x86_64-libtiff \ + mingw-w64-x86_64-freetype \ + mingw-w64-x86_64-lcms2 \ + mingw-w64-x86_64-libwebp \ + mingw-w64-x86_64-openjpeg2 \ + mingw-w64-x86_64-libimagequant \ + mingw-w64-x86_64-libraqm .. tab:: FreeBSD - .. Note:: Only FreeBSD 10 and 11 tested + .. Note:: Only FreeBSD 10 and 11 tested - Make sure you have Python's development libraries installed:: + Make sure you have Python's development libraries installed:: - sudo pkg install python3 + sudo pkg install python3 - Prerequisites are installed on **FreeBSD 10 or 11** with:: + Prerequisites are installed on **FreeBSD 10 or 11** with:: - sudo pkg install jpeg-turbo tiff webp lcms2 freetype2 openjpeg harfbuzz fribidi libxcb + sudo pkg install jpeg-turbo tiff webp lcms2 freetype2 openjpeg harfbuzz fribidi libxcb - Then see ``depends/install_raqm_cmake.sh`` to install libraqm. + Then see ``depends/install_raqm_cmake.sh`` to install libraqm. .. tab:: Android - Basic Android support has been added for compilation within the Termux - environment. The dependencies can be installed by:: + Basic Android support has been added for compilation within the Termux + environment. The dependencies can be installed by:: - pkg install -y python ndk-sysroot clang make \ - libjpeg-turbo + pkg install -y python ndk-sysroot clang make \ + libjpeg-turbo - This has been tested within the Termux app on ChromeOS, on x86. + This has been tested within the Termux app on ChromeOS, on x86. Installing ^^^^^^^^^^ From 61cbcaee64a852bc9902d60ab0732f676d6d0e72 Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Sat, 3 Dec 2022 10:35:01 +1100 Subject: [PATCH 7/8] Changed indentation to be consistent --- docs/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 89b2e558f40..b559c824d11 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -205,11 +205,11 @@ Many of Pillow's features require external libraries: In Fedora, the command is:: - sudo dnf install python3-devel redhat-rpm-config + sudo dnf install python3-devel redhat-rpm-config In Alpine, the command is:: - sudo apk add python3-dev py3-setuptools + sudo apk add python3-dev py3-setuptools .. Note:: ``redhat-rpm-config`` is required on Fedora 23, but not earlier versions. From 61f27211c2d50a20ac544ff8ab16c58439c4cbe8 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sat, 3 Dec 2022 07:43:58 +0200 Subject: [PATCH 8/8] Fix comment Co-authored-by: Andrew Murray <3112309+radarhere@users.noreply.github.com> --- .editorconfig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.editorconfig b/.editorconfig index 07f02c23665..449530717f9 100644 --- a/.editorconfig +++ b/.editorconfig @@ -14,7 +14,7 @@ indent_style = space trim_trailing_whitespace = true [*.rst] -# Three-space indentation +# Four-space indentation indent_size = 4 [*.yml]