diff --git a/doc-requirements.txt b/doc-requirements.txt index e62282562ea0..3432a16d1de7 100644 --- 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 index c2cd95aef458..ac21ed741153 100644 --- 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 index 27dd1b7719a0..ea6b4f8a09c7 100755 --- 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 index ca825f73b008..5141a4cdd37d 100644 --- 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