diff --git a/.circleci/config.yml b/.circleci/config.yml index 239b5f1955c3..aeaecc820647 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -68,7 +68,7 @@ mpl-run: &mpl-install doc-run: &doc-build name: Build documentation - command: python make.py html + command: make html working_directory: doc doc-bundle-run: &doc-bundle diff --git a/.gitignore b/.gitignore index 8191bc39e393..0473729069d6 100644 --- a/.gitignore +++ b/.gitignore @@ -66,9 +66,6 @@ doc/gallery doc/tutorials doc/modules doc/pyplots/tex_demo.png -doc/users/installing.rst -doc/_static/depsy_badge.svg -doc/_static/matplotlibrc lib/dateutil examples/*/*.pdf examples/*/*.png diff --git a/INSTALL.rst b/INSTALL.rst index fdcfecbf1d86..0143329a61ae 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -1,7 +1,3 @@ -.. The source of this document is INSTALL.rst. During the doc build process, -.. this file is copied over to doc/users/installing.rst. -.. Therefore, you must edit INSTALL.rst, *not* doc/users/installing.rst! - .. _pip: https://pypi.python.org/pypi/pip/ ========== @@ -13,7 +9,6 @@ Installing If you wish to contribute to the project, it's recommended you :ref:`install the latest development version`. - .. contents:: Installing an official release diff --git a/doc-requirements.txt b/doc-requirements.txt index ded1a2df68ba..6bae185bf850 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -6,10 +6,10 @@ # Install the documentation requirements with: # pip install -r doc-requirements.txt # -sphinx>=1.3,!=1.5.0 +sphinx>=1.3,!=1.5.0,!=1.6.4 colorspacious ipython mock -numpydoc +numpydoc>=0.4 pillow sphinx-gallery>=0.1.12 diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000000..da3e35fdd41f --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = -W +SPHINXBUILD = python -msphinx +SPHINXPROJ = matplotlib +SOURCEDIR = . +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/README.txt b/doc/README.txt index 3ac8e84205df..f2c2e8d66d41 100644 --- a/doc/README.txt +++ b/doc/README.txt @@ -1,45 +1,13 @@ Matplotlib documentation ======================== - Building the documentation -------------------------- -To build the documentation, you will need additional dependencies: - -* Sphinx-1.3 or later (version 1.5.0 is not supported) -* numpydoc 0.4 or later -* IPython -* mock -* colorspacious -* pillow -* graphviz - -All of these dependencies *except graphviz* can be installed through pip:: - - pip install -r ../doc-requirements.txt - -or all of them via conda and pip:: - - conda install sphinx numpydoc ipython mock graphviz pillow \ - sphinx-gallery - pip install colorspacious - -To build the HTML documentation, type ``python make.py 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 -documentation**: Matplotlib must be installed *before* the docs can be -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. +See :file:`doc/devel/documenting_mpl.rst` for instructions to build the docs. Organization -------------- +------------ This is the top level build directory for the Matplotlib documentation. All of the documentation is written using sphinx, a @@ -57,12 +25,12 @@ 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 - * index.rst - the top level include document for Matplotlib docs * conf.py - the sphinx configuration +* Makefile and make.bat - entry points for building the docs + * _static - used by the sphinx build system * _templates - used by the sphinx build system diff --git a/doc/_static/depsy_badge_default.svg b/doc/_static/depsy_badge_default.svg deleted file mode 100644 index 2fa22b8a14b3..000000000000 --- a/doc/_static/depsy_badge_default.svg +++ /dev/null @@ -1 +0,0 @@ -DepsyDepsy100th percentile100th percentile \ No newline at end of file diff --git a/doc/_templates/badgesidebar.html b/doc/_templates/badgesidebar.html index 1067b5cb9ad7..66d58808aec5 100644 --- a/doc/_templates/badgesidebar.html +++ b/doc/_templates/badgesidebar.html @@ -4,12 +4,6 @@
- - - - -
- Travis-CI: diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 07451f544d15..54b0e608fcd3 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -15,13 +15,14 @@ the Sphinx_ documentation generation tool. There are several extra requirements that are needed to build the documentation. They are listed in :file:`doc-requirements.txt` and listed below: -1. Sphinx 1.3 or later (1.5.0 is not supported) -2. numpydoc 0.4 or later -3. IPython -4. mock -5. colorspacious -6. Pillow -7. Graphviz +* Sphinx>=1.3, !=1.5.0, !=1.6.4 +* colorspacious +* IPython +* mock +* numpydoc>=0.4 +* Pillow +* sphinx-gallery>=0.1.12 +* graphviz .. note:: @@ -69,24 +70,41 @@ Building the docs ----------------- The documentation sources are found in the :file:`doc/` directory in the trunk. -To build the documentation in html format, cd into :file:`doc/` and run: +To build the documentation in html format, cd into :file:`doc/` and run .. code-block:: sh - python make.py html + make html -The list of commands and flags for ``make.py`` can be listed by running -``python make.py --help``. In particular, +Other useful invocations include -* ``python make.py clean`` will delete the built Sphinx files. Use this command - if you're getting strange errors about missing paths or broken links, - particularly if you move files around. -* ``python make.py latex`` builds a PDF of the documentation. -* The ``--allowsphinxwarnings`` flag allows the docs to continue building even - if Sphinx throws a warning. This is useful for debugging and spot-checking - many warnings at once. +.. code-block:: sh + + # Delete built files. May help if you get errors about missing paths or + # broken links. + make clean + + # Build pdf docs. + make latexpdf + +The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into +errors. To unset it, use + +.. code-block:: sh + + make SPHINXOPTS= html + +You can use the ``O`` variable to set additional options: + +* ``make O=-j4 html`` runs a parallel build with 4 processes. +* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution. +* ``make O=-Dplot_gallery=0 html`` skips the gallery build. + +Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0' +html``. -.. _formatting-mpl-docs: +On Windows, options needs to be set as environment variables, e.g. ``set O=-W +-j4 & make html``. Writing new documentation ========================= diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index b26627633dd5..73d7eb8bea39 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -53,9 +53,7 @@ by merging all files in :file:`doc/users/next_whats_new/` coherently. Also, temporarily comment out the include and toctree glob; re-instate these after a release. Finally, make sure that the docs build cleanly :: - pushd doc - python make.py html latex -n 16 - popd + make -Cdoc O=-n$(nproc) html latexpdf After the docs are built, check that all of the links, internal and external, are still valid. We use ``linkchecker`` for this, which has not been ported to python3 yet. You will @@ -214,7 +212,7 @@ build the docs from the ``ver-doc`` branch. An easy way to arrange this is:: git checkout v2.0.0-doc git clean -xfd cd doc - python make.py html latex -n 16 + make O=-n$(nproc) html latexpdf which will build both the html and pdf version of the documentation. diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 000000000000..042c9ef3543b --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,38 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=python -msphinx +) +set SOURCEDIR=. +set BUILDDIR=build +set SPHINXPROJ=matplotlib +set SPHINXOPTS=-W +set O= + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The Sphinx module was not found. Make sure you have Sphinx installed, + echo.then set the SPHINXBUILD environment variable to point to the full + echo.path of the 'sphinx-build' executable. Alternatively you may add the + echo.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" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/make.py b/doc/make.py deleted file mode 100755 index dcdb877e4772..000000000000 --- a/doc/make.py +++ /dev/null @@ -1,228 +0,0 @@ -#!/usr/bin/env python -"""Wrapper script for calling Sphinx. """ - -from __future__ import print_function -import glob -import os -import shutil -import sys -import re -import argparse -import subprocess -import matplotlib -import six - - -def copy_if_out_of_date(original, derived): - """Copy file only if newer as target or if target does not exist. """ - 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(): - """Create target build directories if necessary. """ - 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(): - """Execute Sphinx 'doctest' target. """ - subprocess.call( - [sys.executable] - + '-msphinx -b doctest -d build/doctrees . build/doctest'.split()) - - -def linkcheck(): - """Execute Sphinx 'linkcheck' target. """ - subprocess.call( - [sys.executable] - + '-msphinx -b linkcheck -d build/doctrees . build/linkcheck'.split()) - -DEPSY_PATH = "_static/depsy_badge.svg" -DEPSY_URL = "http://depsy.org/api/package/pypi/matplotlib/badge.svg" -DEPSY_DEFAULT = "_static/depsy_badge_default.svg" - - -def fetch_depsy_badge(): - """Fetches a static copy of the depsy badge. - - If there is any network error, use a static copy from git. - - This is to avoid a mixed-content warning when serving matplotlib.org - over https, see https://github.com/Impactstory/depsy/issues/77 - - The downside is that the badge only updates when the documentation - is rebuilt.""" - try: - request = six.moves.urllib.request.urlopen(DEPSY_URL) - try: - data = request.read().decode('utf-8') - with open(DEPSY_PATH, 'w') as output: - output.write(data) - finally: - request.close() - except six.moves.urllib.error.URLError: - shutil.copyfile(DEPSY_DEFAULT, DEPSY_PATH) - - -def html(buildername='html'): - """Build Sphinx 'html' target. """ - check_build() - fetch_depsy_badge() - - 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') - - options = ['-j{}'.format(n_proc), - '-b{}'.format(buildername), - '-dbuild/doctrees'] - if small_docs: - options += ['-Dplot_formats=png:100'] - if warnings_as_errors: - 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 - for filename in glob.glob('build/%s/_images/*.pdf' % buildername): - os.remove(filename) - - -def htmlhelp(): - """Build Sphinx 'htmlhelp' target. """ - 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(): - """Build Sphinx 'latex' target. """ - check_build() - # figs() - if sys.platform != 'win32': - # LaTeX format. - if subprocess.call( - [sys.executable] - + '-msphinx -b latex -d build/doctrees . build/latex'.split()): - raise SystemExit("Building LaTeX failed.") - - # Produce pdf. - # Call the makefile produced by sphinx... - if subprocess.call("make", cwd="build/latex"): - raise SystemExit("Rendering LaTeX failed with.") - else: - print('latex build has not been tested on windows') - - -def texinfo(): - """Build Sphinx 'texinfo' target. """ - check_build() - # figs() - if sys.platform != 'win32': - # Texinfo format. - if subprocess.call( - [sys.executable] - + '-msphinx -b texinfo -d build/doctrees . build/texinfo'.split()): - raise SystemExit("Building Texinfo failed.") - - # Produce info file. - # Call the makefile produced by sphinx... - if subprocess.call("make", cwd="build/texinfo"): - raise SystemExit("Rendering Texinfo failed with.") - else: - print('texinfo build has not been tested on windows') - - -def clean(): - """Remove generated files. """ - shutil.rmtree("build", ignore_errors=True) - shutil.rmtree("tutorials", ignore_errors=True) - shutil.rmtree("api/_as_gen", ignore_errors=True) - for pattern in ['_static/matplotlibrc', - '_templates/gallery.html', - 'users/installing.rst']: - for filename in glob.glob(pattern): - if os.path.exists(filename): - os.remove(filename) - - -def build_all(): - """Build Sphinx 'html' and 'latex' target. """ - # figs() - html() - latex() - - -funcd = { - 'html': html, - 'htmlhelp': htmlhelp, - 'latex': latex, - 'texinfo': texinfo, - 'clean': clean, - 'all': build_all, - 'doctest': doctest, - 'linkcheck': linkcheck, - } - - -# 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.rst', 'users/installing.rst') - -parser = argparse.ArgumentParser(description='Build matplotlib docs') -parser.add_argument( - "cmd", nargs="*", - help="Command(s) to execute. Valid commands: {}." - .format(", ".join(sorted(funcd)))) -parser.add_argument( - "--small", action="store_true", default=False, - help="Smaller docs with only low resolution PNG figures.") -parser.add_argument( - "--allowsphinxwarnings", action="store_true", default=False, - help="Don't turn Sphinx warnings into errors.") -parser.add_argument( - "-n", type=int, default=1, - help="Number of parallel workers to use.") - -args = parser.parse_args() -small_docs = args.small -warnings_as_errors = not args.allowsphinxwarnings -n_proc = args.n - -_valid_commands = "Valid commnds: {}".format(", ".join(sorted(funcd))) -if args.cmd: - for command in args.cmd: - func = funcd.get(command) - if func is None: - raise SystemExit("Do not know how to handle {}. {}" - .format(command, _valid_commands)) - func() -else: - raise SystemExit(_valid_commands) -os.chdir(current_dir) diff --git a/doc/users/installing.rst b/doc/users/installing.rst new file mode 100644 index 000000000000..545ae4fa153e --- /dev/null +++ b/doc/users/installing.rst @@ -0,0 +1 @@ +.. include:: ../../INSTALL.rst diff --git a/tutorials/introductory/customizing.py b/tutorials/introductory/customizing.py index 03b38b59ac09..0be0daf16d6a 100644 --- a/tutorials/introductory/customizing.py +++ b/tutorials/introductory/customizing.py @@ -180,11 +180,7 @@ # A sample matplotlibrc file # ~~~~~~~~~~~~~~~~~~~~~~~~~~ # -# .. htmlonly:: -# -# `(download) <../../_static/matplotlibrc>`__ -# -# .. literalinclude:: ../../_static/matplotlibrc +# .. literalinclude:: ../../../matplotlibrc.template # # # .. _matplotlibrc: http://matplotlib.org/users/customizing.html