matplotlib · NelleV · Mar 11, 2017 · Mar 11, 2017
diff --git a/doc-requirements.txt b/doc-requirements.txt
@@ -6,7 +6,7 @@
 # Install the documentation requirements with:
 #     pip install -r doc-requirements.txt
 #
-sphinx>1.0,!=1.5.0
+sphinx>1.3,!=1.5.0
 numpydoc
 ipython
 mock

diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -8,7 +8,7 @@ Getting started
 ===============
 
 The documentation for matplotlib is generated from ReStructured Text using the
-Sphinx_ documentation generation tool. Sphinx-1.0 or later and numpydoc 0.4 or
+Sphinx_ documentation generation tool. Sphinx-1.3 or later and numpydoc 0.4 or
 later is required.
 
 The documentation sources are found in the :file:`doc/` directory in

diff --git a/doc/make.py b/doc/make.py
@@ -40,12 +40,16 @@ def check_build():
 
 def doctest():
     """Execute Sphinx 'doctest' target. """
-    os.system('sphinx-build -b doctest -d build/doctrees . build/doctest')
+    subprocess.call(
+        [sys.executable]
+        + '-msphinx -b doctest -d build/doctrees . build/doctest'.split())
 
 
 def linkcheck():
     """Execute Sphinx 'linkcheck' target. """
-    os.system('sphinx-build -b linkcheck -d build/doctrees . build/linkcheck')
+    subprocess.call(
+        [sys.executable]
+        + '-msphinx -b linkcheck -d build/doctrees . build/linkcheck'.split())
 
 
 # For generating PNGs of the top row of index.html:
@@ -81,7 +85,8 @@ def generate_frontpage_pngs(only_if_needed=True):
             continue  # do nothing if png is newer
 
         # Execute python as subprocess (preferred over os.system()):
-        subprocess.check_call(["python", pn_py])  # raises CalledProcessError()
+        subprocess.check_call(
+            [sys.executable, pn_py])  # raises CalledProcessError()
         os.rename(fn_png, pn_png)  # move file to _static/ directory
 
 
@@ -96,14 +101,16 @@ def html(buildername='html'):
         rc = default_rc
     copy_if_out_of_date(rc, '_static/matplotlibrc')
 
+    options = ['-j{}'.format(n_proc),
+               '-b{}'.format(buildername),
+               '-dbuild/doctrees']
     if small_docs:
-        options = "-D plot_formats=png:100"
-    else:
-        options = ''
+        options += ['-Dplot_formats=png:100']
     if warnings_as_errors:
-        options = options + ' -W'
-    if os.system('sphinx-build -j %d %s -b %s -d build/doctrees . build/%s' % (
-            n_proc, options, buildername, buildername)):
+        options += ['-W']
+    if subprocess.call(
+            [sys.executable, '-msphinx', '.', 'build/{}'.format(buildername)]
+            + options):
         raise SystemExit("Building HTML failed.")
 
     # Clean out PDF files from the _images directory
@@ -132,7 +139,9 @@ def latex():
     # figs()
     if sys.platform != 'win32':
         # LaTeX format.
-        if os.system('sphinx-build -b latex -d build/doctrees . build/latex'):
+        if subprocess.call(
+                [sys.executable]
+                + '-msphinx -b latex -d build/doctrees . build/latex'.split()):
             raise SystemExit("Building LaTeX failed.")
 
         # Produce pdf.
@@ -153,8 +162,9 @@ def texinfo():
     # figs()
     if sys.platform != 'win32':
         # Texinfo format.
-        if os.system(
-                'sphinx-build -b texinfo -d build/doctrees . build/texinfo'):
+        if subprocess.call(
+                [sys.executable]
+                + '-msphinx -b texinfo -d build/doctrees . build/texinfo'.split()):
             raise SystemExit("Building Texinfo failed.")
 
         # Produce info file.

diff --git a/lib/matplotlib/sphinxext/tests/test_tinypages.py b/lib/matplotlib/sphinxext/tests/test_tinypages.py
@@ -1,29 +1,32 @@
 """ Tests for tinypages build using sphinx extensions """
 
+import filecmp
+from os.path import join as pjoin, dirname, isdir
 import shutil
-import tempfile
-
-from os.path import (join as pjoin, dirname, isdir)
-
 from subprocess import call, Popen, PIPE
+import sys
+import tempfile
 
 import pytest
 
+from matplotlib import cbook
+
 
 HERE = dirname(__file__)
 TINY_PAGES = pjoin(HERE, 'tinypages')
 
 
 def setup_module():
-    """Check we have the sphinx-build command"""
-    try:
-        ret = call(['sphinx-build', '--help'], stdout=PIPE, stderr=PIPE)
-    except OSError:
-        pytest.skip('Need sphinx-build on path for these tests')
+    """Check we have a recent enough version of sphinx installed.
+    """
+    ret = call([sys.executable, '-msphinx', '--help'],
+               stdout=PIPE, stderr=PIPE)
     if ret != 0:
-        raise RuntimeError('sphinx-build does not return 0')
+        raise RuntimeError(
+            "'{} -msphinx' does not return 0".format(sys.executable))
 
 
+@cbook.deprecated("2.1", alternative="filecmp.cmp")
 def file_same(file1, file2):
     with open(file1, 'rb') as fobj:
         contents1 = fobj.read()
@@ -42,15 +45,16 @@ def setup_class(cls):
             cls.html_dir = pjoin(cls.page_build, 'html')
             cls.doctree_dir = pjoin(cls.page_build, 'doctrees')
             # Build the pages with warnings turned into errors
-            cmd = [str('sphinx-build'), '-W', '-b', 'html',
+            cmd = [sys.executable, '-msphinx', '-W', '-b', 'html',
                    '-d', cls.doctree_dir,
                    TINY_PAGES,
                    cls.html_dir]
             proc = Popen(cmd, stdout=PIPE, stderr=PIPE)
             out, err = proc.communicate()
             if proc.returncode != 0:
-                raise RuntimeError('sphinx-build failed with stdout:\n'
-                                   '{0}\nstderr:\n{1}\n'.format(out, err))
+                raise RuntimeError(
+                    "'{} -msphinx' failed with stdout:\n{}\nstderr:\n{}\n"
+                    .format(sys.executable, out, err))
         except Exception as e:
             shutil.rmtree(cls.page_build)
             raise e
@@ -67,22 +71,22 @@ def plot_file(num):
 
         range_10, range_6, range_4 = [plot_file(i) for i in range(1, 4)]
         # Plot 5 is range(6) plot
-        assert file_same(range_6, plot_file(5))
+        assert filecmp.cmp(range_6, plot_file(5))
         # Plot 7 is range(4) plot
-        assert file_same(range_4, plot_file(7))
+        assert filecmp.cmp(range_4, plot_file(7))
         # Plot 11 is range(10) plot
-        assert file_same(range_10, plot_file(11))
+        assert filecmp.cmp(range_10, plot_file(11))
         # Plot 12 uses the old range(10) figure and the new range(6) figure
-        assert file_same(range_10, plot_file('12_00'))
-        assert file_same(range_6, plot_file('12_01'))
+        assert filecmp.cmp(range_10, plot_file('12_00'))
+        assert filecmp.cmp(range_6, plot_file('12_01'))
         # Plot 13 shows close-figs in action
-        assert file_same(range_4, plot_file(13))
+        assert filecmp.cmp(range_4, plot_file(13))
         # Plot 14 has included source
         with open(pjoin(self.html_dir, 'some_plots.html'), 'rb') as fobj:
             html_contents = fobj.read()
         assert b'# Only a comment' in html_contents
         # check plot defined in external file.
-        assert file_same(range_4, pjoin(self.html_dir, 'range4.png'))
-        assert file_same(range_6, pjoin(self.html_dir, 'range6.png'))
+        assert filecmp.cmp(range_4, pjoin(self.html_dir, 'range4.png'))
+        assert filecmp.cmp(range_6, pjoin(self.html_dir, 'range6.png'))
         # check if figure caption made it into html file
         assert b'This is the caption for plot 15.' in html_contents