From 11de488303ab137989a34e16233994f78667b505 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 28 Jun 2016 11:22:36 -0700 Subject: [PATCH 1/8] ENH doc is now built with the new sphinx build Instead of relying on make.py which is the antiquated way of building sphinx documentation, the build now relies on sphinx-build through a makefile (or make.bat for windows). closes #5798 --- doc/Makefile | 179 +++++++++++++++++++++++++++++++++++++ doc/make.bat | 242 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/make.py | 220 ---------------------------------------------- 3 files changed, 421 insertions(+), 220 deletions(-) create mode 100644 doc/Makefile create mode 100644 doc/make.bat delete mode 100755 doc/make.py diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000000..c0e678e54efb --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,179 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +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 + +all: html + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @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" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/matplotlib.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/matplotlib.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/matplotlib" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/matplotlib" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 000000000000..4174b51ecdf5 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + 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 + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\matplotlib.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\matplotlib.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/doc/make.py b/doc/make.py deleted file mode 100755 index 6028ea68f917..000000000000 --- a/doc/make.py +++ /dev/null @@ -1,220 +0,0 @@ -#!/usr/bin/env python - -from __future__ import print_function -import glob -import os -import shutil -import sys -import re -import argparse -import matplotlib - -def copy_if_out_of_date(original, derived): - if (not os.path.exists(derived) or - os.stat(derived).st_mtime < os.stat(original).st_mtime): - try: - shutil.copyfile(original, derived) - except IOError: - if os.path.basename(original) == 'matplotlibrc': - msg = "'%s' not found. " % original + \ - "Did you run `python setup.py build`?" - raise IOError(msg) - else: - raise - -def check_build(): - build_dirs = ['build', 'build/doctrees', 'build/html', 'build/latex', - 'build/texinfo', '_static', '_templates'] - for d in build_dirs: - try: - os.mkdir(d) - except OSError: - pass - -def doctest(): - os.system('sphinx-build -b doctest -d build/doctrees . build/doctest') - -def linkcheck(): - os.system('sphinx-build -b linkcheck -d build/doctrees . build/linkcheck') - -def html(buildername='html'): - check_build() - - rc = '../lib/matplotlib/mpl-data/matplotlibrc' - default_rc = os.path.join(matplotlib._get_data_path(), 'matplotlibrc') - if not os.path.exists(rc) and os.path.exists(default_rc): - rc = default_rc - copy_if_out_of_date(rc, '_static/matplotlibrc') - - if small_docs: - options = "-D plot_formats=png:100" - else: - options = '' - 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)): - raise SystemExit("Building HTML failed.") - - # Clean out PDF files from the _images directory - for filename in glob.glob('build/%s/_images/*.pdf' % buildername): - os.remove(filename) - - shutil.copy('../CHANGELOG', 'build/%s/_static/CHANGELOG' % buildername) - -def htmlhelp(): - html(buildername='htmlhelp') - # remove scripts from index.html - with open('build/htmlhelp/index.html', 'r+') as fh: - content = fh.read() - fh.seek(0) - content = re.sub(r'', '', content, - flags=re.MULTILINE| re.DOTALL) - fh.write(content) - fh.truncate() - -def latex(): - check_build() - #figs() - if sys.platform != 'win32': - # LaTeX format. - if os.system('sphinx-build -b latex -d build/doctrees . build/latex'): - raise SystemExit("Building LaTeX failed.") - - # Produce pdf. - os.chdir('build/latex') - - # Call the makefile produced by sphinx... - if os.system('make'): - raise SystemExit("Rendering LaTeX failed.") - - os.chdir('../..') - else: - print('latex build has not been tested on windows') - -def texinfo(): - check_build() - #figs() - if sys.platform != 'win32': - # Texinfo format. - if os.system( - 'sphinx-build -b texinfo -d build/doctrees . build/texinfo'): - raise SystemExit("Building Texinfo failed.") - - # Produce info file. - os.chdir('build/texinfo') - - # Call the makefile produced by sphinx... - if os.system('make'): - raise SystemExit("Rendering Texinfo failed.") - - os.chdir('../..') - else: - print('texinfo build has not been tested on windows') - -def clean(): - shutil.rmtree("build", ignore_errors=True) - shutil.rmtree("examples", ignore_errors=True) - for pattern in ['mpl_examples/api/*.png', - 'mpl_examples/pylab_examples/*.png', - 'mpl_examples/pylab_examples/*.pdf', - 'mpl_examples/units/*.png', - 'pyplots/tex_demo.png', - '_static/matplotlibrc', - '_templates/gallery.html', - 'users/installing.rst']: - for filename in glob.glob(pattern): - if os.path.exists(filename): - os.remove(filename) - -def all(): - #figs() - html() - latex() - - -funcd = { - 'html' : html, - 'htmlhelp' : htmlhelp, - 'latex' : latex, - 'texinfo' : texinfo, - 'clean' : clean, - 'all' : all, - 'doctest' : doctest, - 'linkcheck': linkcheck, - } - - -small_docs = False -warnings_as_errors = True -n_proc = 1 - -# Change directory to the one containing this file -current_dir = os.getcwd() -os.chdir(os.path.dirname(os.path.join(current_dir, __file__))) -copy_if_out_of_date('../INSTALL', 'users/installing.rst') - -# Create the examples symlink, if it doesn't exist - -required_symlinks = [ - ('mpl_examples', '../examples/'), - ('mpl_toolkits/axes_grid1/examples', '../../../examples/axes_grid1/'), - ('mpl_toolkits/axisartist/examples', '../../../examples/axisartist/') - ] - -symlink_warnings = [] -for link, target in required_symlinks: - if sys.platform == 'win32' and os.path.isfile(link): - # This is special processing that applies on platforms that don't deal - # with git symlinks -- probably only MS windows. - delete = False - with open(link, 'r') as content: - delete = target == content.read() - if delete: - symlink_warnings.append('deleted: doc/{0}'.format(link)) - os.unlink(link) - else: - raise RuntimeError("doc/{0} should be a directory or symlink -- it" - " isn't".format(link)) - if not os.path.exists(link): - try: - os.symlink(target, link) - except OSError: - symlink_warnings.append('files copied to {0}'.format(link)) - shutil.copytree(os.path.join(link, '..', target), link) - -if sys.platform == 'win32' and len(symlink_warnings) > 0: - print('The following items related to symlinks will show up ' - 'as spurious changes in your \'git status\':\n\t{0}' - .format('\n\t'.join(symlink_warnings))) - -parser = argparse.ArgumentParser(description='Build matplotlib docs') -parser.add_argument("cmd", help=("Command to execute. Can be multiple. " - "Valid options are: %s" % (funcd.keys())), nargs='*') -parser.add_argument("--small", - help="Smaller docs with only low res png figures", - action="store_true") -parser.add_argument("--allowsphinxwarnings", - help="Don't turn Sphinx warnings into errors", - action="store_true") -parser.add_argument("-n", - help="Number of parallel workers to use") - -args = parser.parse_args() -if args.small: - small_docs = True -if args.allowsphinxwarnings: - warnings_as_errors = False -if args.n is not None: - n_proc = int(args.n) - -if args.cmd: - for command in args.cmd: - func = funcd.get(command) - if func is None: - raise SystemExit(('Do not know how to handle %s; valid commands' - ' are %s' % (command, funcd.keys()))) - func() -else: - all() -os.chdir(current_dir) From 9d4bec63af65343281ac7d66a96c6a97cadfaeb9 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 28 Jun 2016 12:27:20 -0700 Subject: [PATCH 2/8] ENH Activated warnings-to-error sphinx option --- doc/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index c0e678e54efb..73624877a7af 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -5,7 +5,7 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = -BUILDDIR = _build +BUILDDIR = build # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) @@ -52,7 +52,7 @@ clean: rm -rf $(BUILDDIR)/* html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -W @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." From 32906a815607c97b5454821d7a3de3eae476570a Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 28 Jun 2016 22:17:47 -0700 Subject: [PATCH 3/8] ENH added a Makefile action to build LR images doc - typing make html-small-images now generates low resolution images in the documentation. - makefile now creates symlinks and others --- doc/Makefile | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index 73624877a7af..cd8445f35fab 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -21,7 +21,7 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext -all: html +all: prepare html help: @echo "Please use \`make ' where is one of" @@ -50,12 +50,21 @@ help: clean: rm -rf $(BUILDDIR)/* + rm -rf examples + rm -rf users/installing.rst + rm -rf _templates/gallery.html html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -W @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +html-small-plots: + $(SPHINXBUILD) -D plot_formats=png:80 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -W + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + + dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @@ -177,3 +186,19 @@ pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + + +prepare: mpl_examples mpl_toolkits/axes_grid1/examples \ + mpl_toolkits/axisartist/examples users/installing.rst + +mpl_examples: ../examples + ln -s $< $@ + +mpl_toolkits/axes_grid1/examples: + ln -s ../../../examples/axes_grid1/ $@ + +mpl_toolkits/axisartist/examples: + ln -s ../../../examples/axisartist/ $@ + +users/installing.rst: ../INSTALL + cp $< $@ From ed05541be821b3cbdec4c4804627622a9c7d902a Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 28 Jun 2016 22:19:15 -0700 Subject: [PATCH 4/8] DOC documents the new way of building sphinx-doc --- doc/README.txt | 10 ++++------ doc/devel/documenting_mpl.rst | 9 ++------- doc/devel/release_guide.rst | 4 ++-- 3 files changed, 8 insertions(+), 15 deletions(-) diff --git a/doc/README.txt b/doc/README.txt index 5a9f8187dcf1..aa3cd5e67142 100644 --- a/doc/README.txt +++ b/doc/README.txt @@ -15,7 +15,7 @@ or conda:: conda install sphinx numpydoc ipython mock colorspacious pillow -To build the HTML documentation, type ``python make.py html`` in this +To build the HTML documentation, type ``make html`` in this directory. The top file of the results will be ./build/html/index.html **Note that Sphinx uses the installed version of the package to build the @@ -24,9 +24,8 @@ generated. You can build the documentation with several options: -* `--small` saves figures in low resolution. -* `--allowsphinxwarnings`: Don't turn Sphinx warnings into errors. -* `-n N` enables parallel build of the documentation using N process. +* `make html-small-plots` saves figures in low resolution. +* `-j N` enables parallel build of the documentation using N process. Organization ------------- @@ -47,7 +46,7 @@ python documentation system built on top of ReST. This directory contains * mpl_toolkits - documentation of individual toolkits that ship with matplotlib -* make.py - the build script to build the html or PDF docs +* Makefile and make.bat - the build script to build the html or PDF docs * index.rst - the top level include document for matplotlib docs @@ -61,4 +60,3 @@ python documentation system built on top of ReST. This directory contains * mpl_examples - a link to the matplotlib examples in case any documentation wants to literal include them - diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 0ac2823a6e16..ca06d92cdbdd 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -15,14 +15,9 @@ The documentation sources are found in the :file:`doc/` directory in the trunk. To build the users guide in html format, cd into :file:`doc/` and do:: - python make.py html + make -or:: - - ./make.py html - -you can also pass a ``latex`` flag to make.py to build a pdf, or pass no -arguments to build everything. +you can also pass a ``latex`` flag to make to build a pdf. The output produced by Sphinx can be configured by editing the :file:`conf.py` file located in the :file:`doc/`. diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index fd8ea2a2f046..c83ec7901593 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -144,8 +144,8 @@ stats for all work done since that release. In the matplotlib source repository, build the documentation:: cd doc - python make.py html - python make.py latex + make html + make latex Then copy the build products into your local checkout of the `matplotlib.github.com` repository (assuming here to be checked out in From ab956b1d3254b9ba6f9866a63c96aaf249a84dce Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 28 Jun 2016 22:25:48 -0700 Subject: [PATCH 5/8] FIX travis now builds docs with new makefile --- .travis.yml | 2 +- doc/Makefile | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.travis.yml b/.travis.yml index 9342444f8fca..8c03d5a950a0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -168,7 +168,7 @@ script: fi else cd doc - python make.py html -n 2 + make html-small-plots -j 2 # We don't build the LaTeX docs here, so linkchecker will complain touch build/html/Matplotlib.pdf # Linkchecker only works with python 2.7 for the time being diff --git a/doc/Makefile b/doc/Makefile index cd8445f35fab..215894f3a5ad 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -54,12 +54,12 @@ clean: rm -rf users/installing.rst rm -rf _templates/gallery.html -html: +html: prepare $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -W @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -html-small-plots: +html-small-plots: prepare $(SPHINXBUILD) -D plot_formats=png:80 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -W @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." From 27d5d96c1d5a1349abb90d13e34cff544ad43d5d Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Wed, 29 Jun 2016 12:08:51 -0700 Subject: [PATCH 6/8] FIX now sphinx builds on systems that aren't utf8 The encoding of files (both when reading and writing) was not specified. This caused the documentation build to fail on systems not configured to use utf8 by default. Now, the sphinx-extension gen_gallery specifies the encoding when reading and writing to files and the documention builds properly on all systems. --- doc/sphinxext/gen_gallery.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/sphinxext/gen_gallery.py b/doc/sphinxext/gen_gallery.py index 9992e788f2f3..11aa4a8e71f1 100644 --- a/doc/sphinxext/gen_gallery.py +++ b/doc/sphinxext/gen_gallery.py @@ -143,14 +143,14 @@ def gen_gallery(app, doctree): gallery_path = os.path.join(app.builder.srcdir, '_templates', 'gallery.html') if os.path.exists(gallery_path): - fh = open(gallery_path, 'r') + fh = open(gallery_path, 'r', encoding="utf-8") regenerate = fh.read() != content fh.close() else: regenerate = True if regenerate: - fh = open(gallery_path, 'w') + fh = open(gallery_path, 'w', encoding="utf-8") fh.write(content) fh.close() From c7e056fe0ef4ec0a7daec2e40214e80fda7fe386 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Wed, 29 Jun 2016 14:33:33 -0700 Subject: [PATCH 7/8] ENH doc uses symbolic link insteal of relying on copying --- .gitignore | 2 - doc/Makefile | 23 +-- doc/_static/matplotlibrc | 1 + doc/users/installing.rst | 333 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 337 insertions(+), 22 deletions(-) create mode 120000 doc/_static/matplotlibrc create mode 100644 doc/users/installing.rst diff --git a/.gitignore b/.gitignore index e2ee588a11bc..aad1fb25715c 100644 --- a/.gitignore +++ b/.gitignore @@ -59,8 +59,6 @@ lib/matplotlib/mpl-data/matplotlibrc ################################# doc/examples doc/_templates/gallery.html -doc/users/installing.rst -doc/_static/matplotlibrc doc/pyplots/tex_demo.png lib/dateutil examples/*/*.pdf diff --git a/doc/Makefile b/doc/Makefile index 215894f3a5ad..21d7171d2456 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -21,7 +21,7 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext -all: prepare html +all: html help: @echo "Please use \`make ' where is one of" @@ -51,15 +51,14 @@ help: clean: rm -rf $(BUILDDIR)/* rm -rf examples - rm -rf users/installing.rst rm -rf _templates/gallery.html -html: prepare +html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -W @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -html-small-plots: prepare +html-small-plots: $(SPHINXBUILD) -D plot_formats=png:80 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -W @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." @@ -186,19 +185,3 @@ pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - - -prepare: mpl_examples mpl_toolkits/axes_grid1/examples \ - mpl_toolkits/axisartist/examples users/installing.rst - -mpl_examples: ../examples - ln -s $< $@ - -mpl_toolkits/axes_grid1/examples: - ln -s ../../../examples/axes_grid1/ $@ - -mpl_toolkits/axisartist/examples: - ln -s ../../../examples/axisartist/ $@ - -users/installing.rst: ../INSTALL - cp $< $@ diff --git a/doc/_static/matplotlibrc b/doc/_static/matplotlibrc new file mode 120000 index 000000000000..8c487aa505b4 --- /dev/null +++ b/doc/_static/matplotlibrc @@ -0,0 +1 @@ +../../lib/matplotlib/mpl-data/matplotlibrc \ No newline at end of file diff --git a/doc/users/installing.rst b/doc/users/installing.rst new file mode 100644 index 000000000000..aade12aab122 --- /dev/null +++ b/doc/users/installing.rst @@ -0,0 +1,333 @@ +.. The source of this document is INSTALL. During the doc build process, +.. this file is copied over to doc/users/installing.rst. +.. Therefore, you must edit INSTALL, *not* doc/users/installing.rst! +.. _pip: https://pypi.python.org/pypi/pip/ + +********** +Installing +********** + +There are many different ways to install matplotlib, and the best way +depends on what operating system you are using, what you already have +installed, and how you want to use it. To avoid wading through all +the details (and potential complications) on this page, there are several +convenient options. + +Installing pre-built packages +============================= + +Most platforms : scientific Python distributions +------------------------------------------------ + +The first option is to use one of the pre-packaged python +distributions that already provide matplotlib built-in. The +Continuum.io Python distribution (`Anaconda +`_ or `miniconda +`_) and the Enthought +distribution `(Canopy) `_ +are both excellent choices that "just work" out of the box for +Windows, OSX and common Linux platforms. Both of these distributions +include matplotlib and *lots* of other useful tools. + + +Linux : using your package manager +---------------------------------- + +If you are on Linux, you might prefer to use your package manager. matplotlib +is packaged for almost every major Linux distribution. + +* Debian / Ubuntu : ``sudo apt-get install python-matplotlib`` +* Fedora / Redhat : ``sudo yum install python-matplotlib`` + +Mac OSX : using pip +------------------- + +If you are on Mac OSX you can probably install matplotlib binaries using the +standard Python installation program pip_. +See :ref:`install_osx_binaries`. + +.. _installing_windows: + +Windows +------- + +If you don't already have Python installed, we recommend using +one of the `scipy-stack compatible Python distributions +`_ such as WinPython, Python(x,y), +Enthought Canopy, or Continuum Anaconda, which have matplotlib and many +of its dependencies, plus other useful packages, preinstalled. + +For `standard Python `_ installations, +install matplotlib using pip_:: + + python -m pip install -U pip setuptools + python -m pip install matplotlib + +In case Python 2.7 or 3.4 are not installed for all users, +the Microsoft Visual C++ 2008 ( +`64 bit `__ +or +`32 bit `__ +for Python 2.7) or Microsoft Visual C++ 2010 ( +`64 bit `__ +or +`32 bit `__ +for Python 3.4) redistributable packages need to be installed. + +Matplotlib depends on `Pillow `_ +for reading and saving JPEG, BMP, and TIFF image files. +Matplotlib requires `MiKTeX `_ and +`GhostScript `_ for rendering text +with LaTeX. +`FFmpeg `_, `avconv `_, +`mencoder `_, or +`ImageMagick `_ are required for the +animation module. + +The following backends should work out of the box: agg, tkagg, ps, +pdf and svg. +For other backends you may need to install +`pycairo `_, +`PyQt4 `_, +`PyQt5 `_, +`PySide `_, +`wxPython `_, +`PyGTK `_, +`Tornado `_, +or GhostScript. + +TkAgg is probably the best backend for interactive use from the +standard Python shell or IPython. It is enabled as the default backend +for the official binaries. GTK3 is not supported on Windows. + +The Windows wheels (:file:`*.whl`) on the `PyPI download page +`_ do not contain test data +or example code. +If you want to try the many demos that come in the matplotlib source +distribution, download the :file:`*.tar.gz` file and look in the +:file:`examples` subdirectory. +To run the test suite, copy the :file:`lib\\matplotlib\\tests` and +:file:`lib\\mpl_toolkits\\tests` directories from the source +distribution to :file:`sys.prefix\\Lib\\site-packages\\matplotlib` and +:file:`sys.prefix\\Lib\\site-packages\\mpl_toolkits` respectively, and +install `nose `_, `mock +`_, Pillow, MiKTeX, GhostScript, +ffmpeg, avconv, mencoder, ImageMagick, and `Inkscape +`_. + + + +.. _install_from_source: + +Installing from source +====================== + +If you are interested in contributing to matplotlib development, +running the latest source code, or just like to build everything +yourself, it is not difficult to build matplotlib from source. Grab +the latest *tar.gz* release file from `the PyPI files page +`_, or if you want to +develop matplotlib or just need the latest bugfixed version, grab the +latest git version :ref:`install-from-git`. + +The standard environment variables `CC`, `CXX`, `PKG_CONFIG` are respected. +This means you can set them if your toolchain is prefixed. This may be used for +cross compiling. + + export CC=x86_64-pc-linux-gnu-gcc + export CXX=x86_64-pc-linux-gnu-g++ + export PKG_CONFIG=x86_64-pc-linux-gnu-pkg-config + +Once you have satisfied the requirements detailed below (mainly +python, numpy, libpng and freetype), you can build matplotlib:: + + cd matplotlib + python setup.py build + python setup.py install + +We provide a `setup.cfg +`_ +file that goes with :file:`setup.py` which you can use to customize +the build process. For example, which default backend to use, whether +some of the optional libraries that matplotlib ships with are +installed, and so on. This file will be particularly useful to those +packaging matplotlib. + +If you have installed prerequisites to nonstandard places and need to +inform matplotlib where they are, edit ``setupext.py`` and add the base +dirs to the ``basedir`` dictionary entry for your ``sys.platform``. +e.g., if the header to some required library is in +``/some/path/include/someheader.h``, put ``/some/path`` in the +``basedir`` list for your platform. + +.. _install_requirements: + +Build requirements +------------------ + +These are external packages which you will need to install before +installing matplotlib. If you are building on OSX, see +:ref:`build_osx`. If you are building on Windows, see +:ref:`build_windows`. If you are installing dependencies with a +package manager on Linux, you may need to install the development +packages (look for a "-dev" postfix) in addition to the libraries +themselves. + + +Required Dependencies +^^^^^^^^^^^^^^^^^^^^^ + +:term:`python` 2.7, 3.4, or 3.5 + `Download python `_. + +:term:`numpy` |minimum_numpy_version| (or later) + array support for python (`download numpy `_) + +`setuptools `__ + Setuptools provides extensions for python package installation. + +:term:`dateutil` 1.1 or later + Provides extensions to python datetime handling. If using pip, + easy_install or installing from source, the installer will attempt + to download and install `python_dateutil` from PyPI. + +`pyparsing `__ + Required for matplotlib's mathtext math rendering support. If + using pip, easy_install or installing from source, the installer + will attempt to download and install `pyparsing` from PyPI. + +`libpng 1.2 (or later) `__ + library for loading and saving :term:`PNG` files (`download + `__). libpng requires + zlib. + +`pytz `__ + Used to manipulate time-zone aware datetimes. http://pypi.python.org/pypi/pytz + +:term:`FreeType` 2.3 or later + Library for reading true type font files. If using pip, easy_install or + installing from source, the installer will attempt to locate FreeType in + expected locations. If it cannot, try installing `pkg-config + `__, + a tool used to find required non-python libraries. + +`cycler `__ 0.10.0 or later + Composable cycle class used for constructing style-cycles + +`functools32` + Required for compatibility if running on versions of Python before + Python 3.2. + +Optional GUI framework +^^^^^^^^^^^^^^^^^^^^^^ + +These are optional packages which you may want to install to use +matplotlib with a user interface toolkit. See +:ref:`what-is-a-backend` for more details on the optional matplotlib +backends and the capabilities they provide. + +:term:`tk` 8.3 or later, not 8.6.0 or 8.6.1 + The TCL/Tk widgets library used by the TkAgg backend. + + Versions 8.6.0 and 8.6.1 are known to have issues that may result + in segfaults when closing multiple windows in the wrong order. + +:term:`pyqt` 4.4 or later + The Qt4 widgets library python wrappers for the Qt4Agg backend + +:term:`pygtk` 2.4 or later + The python wrappers for the GTK widgets library for use with the + GTK or GTKAgg backend + +:term:`wxpython` 2.8 or later + The python wrappers for the wx widgets library for use with the + WX or WXAgg backend + +Optional external programs +^^^^^^^^^^^^^^^^^^^^^^^^^^ +`ffmpeg `__/`avconv `__ or `mencoder `__ + Required for the animation module to be save out put to movie + formats. + +`ImageMagick `__ + Required for the animation module to be able to save to animated gif. + +Optional dependencies +^^^^^^^^^^^^^^^^^^^^^ + +`Pillow `__ + If Pillow is installed, matplotlib can read and write a larger + selection of image file formats. + +`pkg-config `__ + A tool used to find required non-python libraries. This is not strictly + required, but can make installation go more smoothly if the libraries and + headers are not in the expected locations. + + +Required libraries that ship with matplotlib +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:term:`agg` 2.4 + The antigrain C++ rendering engine. matplotlib links against the + agg template source statically, so it will not affect anything on + your system outside of matplotlib. + +`qhull` 2012.1 + A library for computing Delaunay triangulations. + +`ttconv` + truetype font utility + +six 1.9.0 + Python 2/3 compatibility library. Do not use this in third-party + code. + + +.. _build_linux: + +Building on Linux +----------------- + +It is easiest to use your system package manager to install the dependencies. + +If you are on Debian/Ubuntu, you can get all the dependencies +required to build matplotlib with:: + + sudo apt-get build-dep python-matplotlib + +If you are on Fedora/RedHat, you can get all the dependencies required +to build matplotlib by first installing ``yum-builddep`` and then +running:: + + su -c "yum-builddep python-matplotlib" + +This does not build matplotlib, but it does get and install the +build dependencies, which will make building from source easier. + + +.. _build_osx: + +Building on OSX +--------------- + +The build situation on OSX is complicated by the various places one +can get the libpng and freetype requirements (darwinports, fink, +/usr/X11R6) and the different architectures (e.g., x86, ppc, universal) and +the different OSX version (e.g., 10.4 and 10.5). We recommend that you build +the way we do for the OSX release: get the source from the tarball or the +git repository and follow the instruction in :file:`README.osx`. + + +.. _build_windows: + +Building on Windows +------------------- + +The Python shipped from http://www.python.org is compiled with Visual Studio +2008 for versions before 3.3, Visual Studio 2010 for 3.3 and 3.4, and +Visual Studio 2015 for 3.5. Python extensions are recommended to be compiled +with the same compiler. + +Since there is no canonical Windows package manager, the methods for building +freetype, zlib, and libpng from source code are documented as a build script +at `matplotlib-winbuild `_. From c6432b40310e83c7149bbb4ef316ec42ecbf6f96 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Wed, 29 Jun 2016 15:35:40 -0700 Subject: [PATCH 8/8] FIX documentation nitpick --- doc/README.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/README.txt b/doc/README.txt index aa3cd5e67142..52cff69fd8e9 100644 --- a/doc/README.txt +++ b/doc/README.txt @@ -25,7 +25,7 @@ generated. You can build the documentation with several options: * `make html-small-plots` saves figures in low resolution. -* `-j N` enables parallel build of the documentation using N process. +* `make -j N` enables parallel build of the documentation using N process. Organization -------------