Switch to makefile-based doc build.

anntzer · anntzer · commit 8886a19f964b · 2017-12-01T01:14:29.000-08:00
diff --git 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 O=-W html
   working_directory: doc
 
 doc-bundle-run: &doc-bundle
diff --git 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
@@ -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<install_from_source>`.
 
-
 .. contents::
 
 Installing an official release
diff --git 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
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+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
@@ -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
diff --git a/doc/_templates/badgesidebar.html b/doc/_templates/badgesidebar.html
@@ -4,12 +4,6 @@
 
 <br/>
 
-<a href="http://depsy.org/package/python/matplotlib">
-  <img src="{{ pathto('_static/depsy_badge.svg', 1) }}">
-</a>
-
-<br/>
-
 Travis-CI: <a href="https://travis-ci.org/matplotlib/matplotlib">
   <img src="https://travis-ci.org/matplotlib/matplotlib.svg?branch=master"/>
 </a>
diff --git 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,34 @@ 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
+
+You can build the documentation with several options:
+
+* ``make O=-W html`` turns Sphinx warnings into errors.  The continuous
+  integration script uses this option.
+* ``make O=-j4 html`` (for example) 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.
 
-.. _formatting-mpl-docs:
+Multiple options can be combined using e.g. ``make O='-W -j4 ...' html``.  On
+Windows, the option needs to be set as the ``SPHINXOPTS`` environment
+variable, e.g. ``set SPHINXOPTS=-W -j4 & make html``.
 
 Writing new documentation
 =========================
diff --git 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
@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=.
+set BUILDDIR=build
+set SPHINXPROJ=matplotlib
+
+%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%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd
diff --git a/doc/make.py b/doc/make.py
diff --git a/doc/users/installing.rst b/doc/users/installing.rst
diff --git a/tutorials/introductory/customizing.py b/tutorials/introductory/customizing.py
