Merge branch 'master' into smart_latex_conf_py

CONTRIBUTING.rst

@@ -272,10 +272,7 @@ Coding Guide
   generated output.
 
 * When adding a new configuration variable, be sure to document it and update
-  :file:`sphinx/quickstart.py` if it's important enough.
-
-* Use the included :program:`utils/check_sources.py` script to check for
-  common formatting issues (trailing whitespace, lengthy lines, etc).
+  :file:`sphinx/cmd/quickstart.py` if it's important enough.
 
 * Add appropriate unit tests.
 

doc/usage/configuration.rst

@@ -1713,9 +1713,9 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 
    This flag determines if sphinx should try to fix image formats that are not
    supported by some epub readers.  At the moment palette images with a small
-   color table are upgraded.  You need the Python Image Library (Pillow the
-   successor of the PIL) installed to use this option.  The default value is
-   ``False`` because the automatic conversion may lose information.
+   color table are upgraded.  You need Pillow, the Python Image Library,
+   installed to use this option.  The default value is ``False`` because the
+   automatic conversion may lose information.
 
    .. versionadded:: 1.2
 

sphinx/builders/_epub_base.py

@@ -29,10 +29,7 @@ from sphinx.util.osutil import ensuredir, copyfile
 try:
     from PIL import Image
 except ImportError:
-    try:
-        import Image
-    except ImportError:
-        Image = None
+    Image = None
 
 if False:
     # For type annotation
@@ -401,9 +398,9 @@ class EpubBuilder(StandaloneHTMLBuilder):
 
     def copy_image_files_pil(self):
         # type: () -> None
-        """Copy images using the PIL.
-        The method tries to read and write the files with the PIL,
-        converting the format and resizing the image if necessary/possible.
+        """Copy images using Pillow, the Python Imaging Libary.
+        The method tries to read and write the files with Pillow, converting
+        the format and resizing the image if necessary/possible.
         """
         ensuredir(path.join(self.outdir, self.imagedir))
         for src in status_iterator(self.images, 'copying images... ', "brown",
@@ -424,7 +421,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
                 continue
             if self.config.epub_fix_images:
                 if img.mode in ('P',):
-                    # See PIL documentation for Image.convert()
+                    # See the Pillow documentation for Image.convert()
+                    # https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.convert
                     img = img.convert()
             if self.config.epub_max_image_width > 0:
                 (width, height) = img.size
@@ -441,12 +439,12 @@ class EpubBuilder(StandaloneHTMLBuilder):
     def copy_image_files(self):
         # type: () -> None
         """Copy image files to destination directory.
-        This overwritten method can use the PIL to convert image files.
+        This overwritten method can use Pillow to convert image files.
         """
         if self.images:
             if self.config.epub_fix_images or self.config.epub_max_image_width:
                 if not Image:
-                    logger.warning(__('PIL not found - copying image files'))
+                    logger.warning(__('Pillow not found - copying image files'))
                     super().copy_image_files()
                 else:
                     self.copy_image_files_pil()

sphinx/cmd/quickstart.py

@@ -395,13 +395,6 @@ def generate(d, overwrite=True, silent=False, templatedir=None):
     d['project_doc_texescaped'] = (d['project'] + ' Documentation').\
         translate(texescape.tex_escape_map)
 
-    # escape backslashes and single quotes in strings that are put into
-    # a Python string literal
-    for key in ('project', 'project_doc', 'project_doc_texescaped',
-                'author', 'author_texescaped', 'copyright',
-                'version', 'release', 'master'):
-        d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
-
     ensuredir(d['path'])
 
     srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']

sphinx/templates/quickstart/conf.py_t

@@ -13,12 +13,12 @@
 {% if append_syspath -%}
 import os
 import sys
-sys.path.insert(0, '{{ module_path }}')
+sys.path.insert(0, {{ module_path | repr }})
 {% else -%}
 # import os
 # import sys
 {% if module_path -%}
-# sys.path.insert(0, '{{ module_path }}')
+# sys.path.insert(0, {{ module_path | repr }})
 {% else -%}
 # sys.path.insert(0, os.path.abspath('.'))
 {% endif -%}
@@ -26,14 +26,14 @@ sys.path.insert(0, '{{ module_path }}')
 
 # -- Project information -----------------------------------------------------
 
-project = '{{ project_str }}'
-copyright = '{{ copyright_str }}'
-author = '{{ author_str }}'
+project = {{ project | repr }}
+copyright = {{ copyright | repr }}
+author = {{ author | repr }}
 
 # The short X.Y version
-version = '{{ version_str }}'
+version = {{ version | repr }}
 # The full version, including alpha/beta/rc tags
-release = '{{ release_str }}'
+release = {{ release | repr }}
 
 
 # -- General configuration ---------------------------------------------------
@@ -54,11 +54,11 @@ templates_path = ['{{ dot }}templates']
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '{{ suffix }}'
+source_suffix = {{ suffix | repr }}
 
 {% if master_doc != 'index' -%}
 # The master toctree document.
-master_doc = '{{ master_str }}'
+master_doc = {{ master | repr }}
 
 {% endif -%}
 # The language for content autogenerated by Sphinx. Refer to documentation

sphinx/util/images.py

@@ -21,12 +21,9 @@ import imagesize
 from sphinx.deprecation import RemovedInSphinx30Warning
 
 try:
-    from PIL import Image        # check for the Python Imaging Library
+    from PIL import Image
 except ImportError:
-    try:
-        import Image
-    except ImportError:
-        Image = None
+    Image = None
 
 if False:
     # For type annotation
@@ -53,7 +50,7 @@ def get_image_size(filename):
         if size[0] == -1:
             size = None
 
-        if size is None and Image:  # fallback to PIL
+        if size is None and Image:  # fallback to Pillow
             im = Image.open(filename)
             size = im.size
             try:
@@ -81,6 +78,8 @@ def guess_mimetype(filename='', content=None, default=None):
     if ext in mime_suffixes:
         return mime_suffixes[ext]
     elif content:
+        # TODO: When the content argument is removed, make filename a required
+        # argument.
         warnings.warn('The content argument of guess_mimetype() is deprecated.',
                       RemovedInSphinx30Warning, stacklevel=2)
         return guess_mimetype_for_stream(BytesIO(content), default=default)