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/.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 new file mode 100644 index 000000000000..21d7171d2456 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,187 @@ +# 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)/* + rm -rf examples + 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 + @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/README.txt b/doc/README.txt index 5a9f8187dcf1..52cff69fd8e9 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. +* `make -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/_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/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 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) 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() 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 `_.