matplotlib · dstansby · Apr 11, 2017 · Mar 8, 2017 · Mar 9, 2017 · Mar 11, 2017
diff --git a/.gitignore b/.gitignore
@@ -32,6 +32,7 @@
 build
 # sphinx build directory
 doc/_build
+doc/gallery
 # setup.py dist directory
 dist
 # Egg metadata
@@ -57,12 +58,13 @@ lib/matplotlib/mpl-data/matplotlibrc
 
 # Documentation generated files #
 #################################
+doc/api/_as_gen
 doc/examples
-doc/_templates/gallery.html
+# autogenerated by sphinx-gallery
+doc/modules
+doc/pyplots/tex_demo.png
 doc/users/installing.rst
 doc/_static/matplotlibrc
-doc/pyplots/tex_demo.png
-doc/api/_as_gen
 lib/dateutil
 examples/*/*.pdf
 examples/*/*.png

diff --git a/.travis.yml b/.travis.yml
@@ -142,6 +142,7 @@ install:
     pip install -ve .
 
 script: source ci/travis/test_script.sh
+
 before_cache:
   - rm -rf $HOME/.cache/matplotlib/tex.cache
   - rm -rf $HOME/.cache/matplotlib/test_cache

diff --git a/ci/travis/test_script.sh b/ci/travis/test_script.sh
@@ -30,7 +30,7 @@ if [[ $BUILD_DOCS == false ]]; then
   fi
 else
   cd doc
-  python make.py html -n 2
+  python make.py html
   # 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-requirements.txt b/doc-requirements.txt
@@ -12,3 +12,4 @@ ipython
 mock
 colorspacious
 pillow
+sphinx-gallery
diff --git a/doc/README.txt b/doc/README.txt
@@ -21,7 +21,8 @@ All of these dependencies *except graphviz* can be installed through pip::
 
 or all of them via conda and pip::
 
-  conda install sphinx numpydoc ipython mock graphviz pillow
+  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

diff --git a/doc/_templates/index.html b/doc/_templates/index.html
@@ -75,7 +75,8 @@ <h1>Introduction</h1>
   <p>Matplotlib tries to make easy things easy and hard things possible.
   You can generate plots, histograms, power spectra, bar charts,
   errorcharts, scatterplots, etc., with just a few lines of code.
-  For a sampling, see the <a href="{{ pathto('users/screenshots') }}">screenshots</a>, <a href="{{ pathto('gallery') }}">thumbnail</a> gallery,  and
+  For a sampling, see the <a href="{{ pathto('users/screenshots')
+  }}">screenshots</a>, <a href="{{ pathto('gallery/index') }}">thumbnail</a> gallery,  and
     <a href="{{ pathto('examples/index') }}">examples</a> directory</p>
 
 <p>For simple plotting the <tt>pyplot</tt> module provides a
@@ -99,7 +100,7 @@ <h1>Documentation</h1>
   </script>
 
   <p>Trying to learn how to do a particular kind of plot?  Check out
-  the <a href="{{ pathto('gallery') }}">gallery</a>, <a href="{{ pathto('examples/index') }}">examples</a>,
+  the <a href="{{ pathto('gallery/index') }}">gallery</a>, <a href="{{ pathto('examples/index') }}">examples</a>,
   or the <a href="{{ pathto('api/pyplot_summary') }}">list of plotting
   commands</a>.</p>
 

diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
@@ -39,7 +39,7 @@ <h3>{{ _('Navigation') }}</h3>
 
         <li><a href="{{ pathto('index') }}">home</a>|&nbsp;</li>
         <li><a href="{{ pathto('examples/index') }}">examples</a>|&nbsp;</li>
-        <li><a href="{{ pathto('gallery') }}">gallery</a>|&nbsp;</li>
+        <li><a href="{{ pathto('gallery/index') }}">gallery</a>|&nbsp;</li>
         <li><a href="{{ pathto('api/pyplot_summary') }}">pyplot</a>|&nbsp;</li>
         <li><a href="{{ pathto('contents') }}">docs</a> &raquo;</li>
 

diff --git a/doc/conf.py b/doc/conf.py
@@ -29,9 +29,10 @@
 extensions = ['matplotlib.sphinxext.mathmpl', 'sphinxext.math_symbol_table',
               'sphinx.ext.autodoc', 'matplotlib.sphinxext.only_directives',
               'sphinx.ext.doctest', 'sphinx.ext.autosummary',
-              'matplotlib.sphinxext.plot_directive',
               'sphinx.ext.inheritance_diagram',
-              'sphinxext.gen_gallery', 'sphinxext.gen_rst',
+              'sphinx_gallery.gen_gallery',
+              'sphinxext.gen_rst',
+              'matplotlib.sphinxext.plot_directive',
               'sphinxext.github',
               'numpydoc']
 
@@ -53,6 +54,12 @@
     raise ImportError("No module named numpydoc - you need to install "
                       "numpydoc to build the documentation.")
 
+try:
+    import sphinx_gallery
+except ImportError:
+    raise ImportError("No module named sphinx_gallery - you need to install "
+                      "sphinx_gallery to build the documentation.")
+
 try:
     import colorspacious
 except ImportError:
@@ -96,6 +103,15 @@
 
 autodoc_docstring_signature = True
 
+
+# Sphinx gallery configuration
+sphinx_gallery_conf = {
+    'examples_dirs': '../examples',
+    'filename_pattern': '\.py$',
+    'gallery_dirs': 'gallery'}
+
+plot_gallery = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -234,7 +250,6 @@
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 html_additional_pages = {'index': 'index.html',
-                         'gallery':'gallery.html',
                          'citing': 'citing.html'}
 
 # If false, no module index is generated.

diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -442,7 +442,7 @@ We have hundreds of examples in subdirectories of
 :file:`matplotlib/examples`, and these are automatically generated
 when the website is built to show up both in the `examples
 <../examples/index.html>`_ and `gallery
-<../gallery.html>`_ sections of the website.
+<../gallery/index.html>`_ sections of the website.
 
 Any sample data that the example uses should be kept small and
 distributed with Matplotlib in the

diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -353,7 +353,7 @@ some ratio which controls the ratio::
 
 .. htmlonly::
 
-    See :ref:`subplots_axes_and_figures-plot_equal_aspect_ratio` for a complete
+    See :ref:`subplots_axes_and_figures-equal_aspect_ratio` for a complete
     example.
 
 
@@ -398,7 +398,7 @@ locators as desired because the two axes are independent.
 
 .. htmlonly::
 
-    See :ref:`api-plot_two_scales` for a complete example
+    See :ref:`api-two_scales` for a complete example
 
 .. _howto-batch:
 
@@ -644,7 +644,7 @@ For more on configuring your backend, see
 
 Alternatively, you can avoid pylab/pyplot altogether, which will give
 you a little more control, by calling the API directly as shown in
-:ref:`api-plot_agg_oo`.
+:ref:`api-agg_oo`.
 
 You can either generate hardcopy on the filesystem by calling savefig::
 

diff --git a/doc/make.py b/doc/make.py
@@ -57,10 +57,10 @@ def linkcheck():
 FRONTPAGE_PY_PATH = "../examples/frontpage/"  # python scripts location
 FRONTPAGE_PNG_PATH = "_static/"  # png files location
 # png files and corresponding generation scripts:
-FRONTPAGE_PNGS = {"surface3d_frontpage.png": "plot_3D.py",
-                  "contour_frontpage.png":   "plot_contour.py",
-                  "histogram_frontpage.png": "plot_histogram.py",
-                  "membrane_frontpage.png":  "plot_membrane.py"}
+FRONTPAGE_PNGS = {"surface3d_frontpage.png": "3D.py",
+                  "contour_frontpage.png":   "contour.py",
+                  "histogram_frontpage.png": "histogram.py",
+                  "membrane_frontpage.png":  "membrane.py"}
 
 
 def generate_frontpage_pngs(only_if_needed=True):

diff --git a/doc/mpl_toolkits/index.rst b/doc/mpl_toolkits/index.rst
@@ -30,7 +30,7 @@ plotting (scatter, surf, line, mesh) tools.  Not the fastest or feature
 complete 3D library out there, but ships with Matplotlib and thus may be a
 lighter weight solution for some use cases.
 
-.. plot:: mpl_examples/mplot3d/contourf3d_demo2.py
+.. plot:: gallery/mplot3d/contourf3d_2.py
 
 .. _toolkit_axes_grid1:
 

diff --git a/doc/mpl_toolkits/mplot3d/tutorial.rst b/doc/mpl_toolkits/mplot3d/tutorial.rst
@@ -36,41 +36,41 @@ Line plots
 ====================
 .. automethod:: Axes3D.plot
 
-.. plot:: mpl_examples/mplot3d/lines3d_demo.py
+.. plot:: gallery/mplot3d/lines3d.py
 
 .. _scatter3d:
 
 Scatter plots
 =============
 .. automethod:: Axes3D.scatter
 
-.. plot:: mpl_examples/mplot3d/scatter3d_demo.py
+.. plot:: gallery/mplot3d/scatter3d.py
 
 .. _wireframe:
 
 Wireframe plots
 ===============
 .. automethod:: Axes3D.plot_wireframe
 
-.. plot:: mpl_examples/mplot3d/wire3d_demo.py
+.. plot:: gallery/mplot3d/wire3d.py
 
 .. _surface:
 
 Surface plots
 =============
 .. automethod:: Axes3D.plot_surface
 
-.. plot:: mpl_examples/mplot3d/surface3d_demo.py
-.. plot:: mpl_examples/mplot3d/surface3d_demo2.py
-.. plot:: mpl_examples/mplot3d/surface3d_demo3.py
+.. plot:: gallery/mplot3d/surface3d.py
+.. plot:: gallery/mplot3d/surface3d_2.py
+.. plot:: gallery/mplot3d/surface3d_3.py
 
 .. _trisurface:
 
 Tri-Surface plots
 =================
 .. automethod:: Axes3D.plot_trisurf
 
-.. plot:: mpl_examples/mplot3d/trisurf3d_demo.py
+.. plot:: gallery/mplot3d/trisurf3d.py
 
 
 .. _contour3d:
@@ -79,18 +79,18 @@ Contour plots
 =============
 .. automethod:: Axes3D.contour
 
-.. plot:: mpl_examples/mplot3d/contour3d_demo.py
-.. plot:: mpl_examples/mplot3d/contour3d_demo2.py
-.. plot:: mpl_examples/mplot3d/contour3d_demo3.py
+.. plot:: gallery/mplot3d/contour3d.py
+.. plot:: gallery/mplot3d/contour3d_2.py
+.. plot:: gallery/mplot3d/contour3d_3.py
 
 .. _contourf3d:
 
 Filled contour plots
 ====================
 .. automethod:: Axes3D.contourf
 
-.. plot:: mpl_examples/mplot3d/contourf3d_demo.py
-.. plot:: mpl_examples/mplot3d/contourf3d_demo2.py
+.. plot:: gallery/mplot3d/contourf3d.py
+.. plot:: gallery/mplot3d/contourf3d_2.py
 
 .. versionadded:: 1.1.0
    The feature demoed in the second contourf3d example was enabled as a
@@ -102,37 +102,37 @@ Polygon plots
 ====================
 .. automethod:: Axes3D.add_collection3d
 
-.. plot:: mpl_examples/mplot3d/polys3d_demo.py
+.. plot:: gallery/mplot3d/polys3d.py
 
 .. _bar3d:
 
 Bar plots
 ====================
 .. automethod:: Axes3D.bar
 
-.. plot:: mpl_examples/mplot3d/bars3d_demo.py
+.. plot:: gallery/mplot3d/bars3d.py
 
 .. _quiver3d:
 
 Quiver
 ====================
 .. automethod:: Axes3D.quiver
 
-.. plot:: mpl_examples/mplot3d/quiver3d_demo.py
+.. plot:: gallery/mplot3d/quiver3d.py
 
 .. _2dcollections3d:
 
 2D plots in 3D
 ====================
-.. plot:: mpl_examples/mplot3d/2dcollections3d_demo.py
+.. plot:: gallery/mplot3d/2dcollections3d.py
 
 .. _text3d:
 
 Text
 ====================
 .. automethod:: Axes3D.text
 
-.. plot:: mpl_examples/mplot3d/text3d_demo.py
+.. plot:: gallery/mplot3d/text3d.py
 
 .. _3dsubplots:
 
@@ -146,5 +146,5 @@ in the same figure.
    Subplotting 3D plots was added in v1.0.0.  Earlier version can not
    do this.
 
-.. plot:: mpl_examples/mplot3d/subplot3d_demo.py
-.. plot:: mpl_examples/mplot3d/mixed_subplots_demo.py
+.. plot:: gallery/mplot3d/subplot3d.py
+.. plot:: gallery/mplot3d/mixed_subplots.py
-Original file line number
+Diff line change
@@ Expand Up / @@ -12,3 +12,4 @@ ipython @@
     mock
     colorspacious
     pillow
+    sphinx-gallery