Merge pull request #5498 from hugovk/improve-docs

Build docs with sphinx_copybutton and sphinxext.opengraph

.github/workflows/test.yml

@@ -103,7 +103,7 @@ jobs:
     - name: Docs
       if: startsWith(matrix.os, 'ubuntu') && matrix.python-version == 3.9
       run: |
-        python3 -m pip install sphinx-issues sphinx-removed-in sphinx-rtd-theme
+        python3 -m pip install sphinx-copybutton sphinx-issues sphinx-removed-in sphinx-rtd-theme sphinxext-opengraph
         make doccheck
 
     - name: After success

docs/conf.py

@@ -29,11 +29,13 @@ needs_sphinx = "2.4"
 # 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_issues",
-    "sphinx_removed_in",
+    "sphinxext.opengraph",
 ]
 
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
@@ -316,3 +318,10 @@ def setup(app):
 
 # GitHub repo for sphinx-issues
 issues_github_path = "python-pillow/Pillow"
+
+# sphinxext.opengraph
+ogp_image = (
+    "https://raw.githubusercontent.com/python-pillow/pillow-logo/master/"
+    "pillow-logo-dark-text-1280x640.png"
+)
+ogp_image_alt = "Pillow"

docs/installation.rst

@@ -6,9 +6,9 @@ Warnings
 
 .. warning:: Pillow and PIL cannot co-exist in the same environment. Before installing Pillow, please uninstall PIL.
 
-.. warning:: Pillow >= 1.0 no longer supports "import Image". Please use "from PIL import Image" instead.
+.. warning:: Pillow >= 1.0 no longer supports ``import Image``. Please use ``from PIL import Image`` instead.
 
-.. warning:: Pillow >= 2.1.0 no longer supports "import _imaging". Please use "from PIL.Image import core as _imaging" instead.
+.. warning:: Pillow >= 2.1.0 no longer supports ``import _imaging``. Please use ``from PIL.Image import core as _imaging`` instead.
 
 Python Support
 --------------

requirements.txt

@@ -10,6 +10,8 @@ pytest
 pytest-cov
 pytest-timeout
 sphinx>=2.4
+sphinx-copybutton
 sphinx-issues
 sphinx-removed-in
 sphinx-rtd-theme
+sphinxext-opengraph