matplotlib · anntzer · May 25, 2018
diff --git a/.gitignore b/.gitignore
@@ -60,10 +60,11 @@ lib/matplotlib/mpl-data/matplotlibrc
 # sphinx build directory
 doc/_build
 doc/api/_as_gen
-# autogenerated by sphinx-gallery
-doc/examples
-doc/gallery
-doc/tutorials
+# autogenerated by sphinx-exhibit
+doc/gallery/*
+!doc/gallery/index.rst
+doc/tutorials/*
+!doc/tutorials/index.rst
 doc/modules
 doc/pyplots/tex_demo.png
 lib/dateutil
@@ -72,6 +73,7 @@ examples/*/*.pdf
 examples/*/*.png
 examples/*/*.svg
 examples/*/*.svgz
+examples/*/*.mp4
 examples/tests/*
 !examples/tests/backend_driver_sgskip.py
 result_images

diff --git a/doc-requirements.txt b/doc-requirements.txt
@@ -13,3 +13,5 @@ ipywidgets
 numpydoc>=0.4
 pillow
 sphinx-gallery>=0.1.13
+git+https://github.com/anntzer/sphinx-exhibit
+sphinx-jinja>=1.1.0
diff --git a/doc/_templates/autosummary.rst b/doc/_templates/autosummary.rst
@@ -1,30 +1,10 @@
 {{ fullname | escape | underline }}
 
-
 .. currentmodule:: {{ module }}
 
-
-{% if objtype in ['class'] %}
+{% if objtype == 'class' %}
 .. auto{{ objtype }}:: {{ objname }}
-    :show-inheritance:
-
+   :show-inheritance:
 {% else %}
 .. auto{{ objtype }}:: {{ objname }}
-
-{% endif %}
-
-{% if objtype in ['class', 'method', 'function'] %}
-{% if objname in ['AxesGrid', 'Scalable', 'HostAxes', 'FloatingAxes',
-                      'ParasiteAxesAuxTrans', 'ParasiteAxes'] %}
-.. Filter out the above aliases to other classes, as sphinx gallery
-   creates no example file for those (sphinx-gallery/sphinx-gallery#365)
-
-{% else %}
-.. include:: {{module}}.{{objname}}.examples
-
-.. raw:: html
-
-    <div class="clearer"></div>
-
-{% endif %}
 {% endif %}
diff --git a/doc/_templates/function.rst b/doc/_templates/function.rst
@@ -5,8 +5,6 @@
 
 .. autofunction:: {{ objname }}
 
-.. include:: {{module}}.{{objname}}.examples
-
 .. raw:: html
 
-    <div class="clearer"></div>
+    <div class="clearer"></div>
diff --git a/doc/conf.py b/doc/conf.py
@@ -36,7 +36,8 @@
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'numpydoc',  # Needs to be loaded *after* autodoc.
-    'sphinx_gallery.gen_gallery',
+    'sphinx_exhibit',
+    'sphinxcontrib.jinja',
     'matplotlib.sphinxext.mathmpl',
     'matplotlib.sphinxext.plot_directive',
     'sphinxext.custom_roles',
@@ -55,6 +56,7 @@ def _check_deps():
              "matplotlib": 'matplotlib',
              "numpydoc": 'numpydoc',
              "PIL.Image": 'pillow',
+             "sphinx_exhibit": 'sphinx_exhibit',
              "sphinx_gallery": 'sphinx_gallery'}
     missing = []
     for name in names:
@@ -69,13 +71,6 @@ def _check_deps():
 
 _check_deps()
 
-# Import only after checking for dependencies.
-# gallery_order.py from the sphinxext folder provides the classes that
-# allow custom ordering of sections and subsections of the gallery
-import sphinxext.gallery_order as gallery_order
-# The following import is only necessary to monkey patch the signature later on
-from sphinx_gallery import gen_rst
-
 if shutil.which('dot') is None:
     raise OSError(
         "No binary named dot - you need to install the Graph Visualization "
@@ -94,36 +89,6 @@ def _check_deps():
     'cycler': ('https://matplotlib.org/cycler', None),
 }
 
-
-# Sphinx gallery configuration
-sphinx_gallery_conf = {
-    'examples_dirs': ['../examples', '../tutorials'],
-    'filename_pattern': '^((?!sgskip).)*$',
-    'gallery_dirs': ['gallery', 'tutorials'],
-    'doc_module': ('matplotlib', 'mpl_toolkits'),
-    'reference_url': {
-        'matplotlib': None,
-        'numpy': 'https://docs.scipy.org/doc/numpy',
-        'scipy': 'https://docs.scipy.org/doc/scipy/reference',
-    },
-    'backreferences_dir': 'api/_as_gen',
-    'subsection_order': gallery_order.sectionorder,
-    'within_subsection_order': gallery_order.subsectionorder,
-    'min_reported_time': 1,
-}
-
-plot_gallery = 'True'
-
-# Monkey-patching gallery signature to include search keywords
-gen_rst.SPHX_GLR_SIG = """\n
-.. only:: html
-
- .. rst-class:: sphx-glr-signature
-
-    Keywords: matplotlib code example, codex, python plot, pyplot
-    `Gallery generated by Sphinx-Gallery
-    <https://sphinx-gallery.readthedocs.io>`_\n"""
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -325,3 +290,46 @@ def _check_deps():
 # numpydoc config
 
 numpydoc_show_class_members = False
+
+# Other configs.
+
+from pathlib import Path
+jinja_contexts = {
+    "default": {
+        "examples": sorted(
+            dirpath.name
+            for dirpath in (Path(__file__).parent / "../examples").iterdir()
+            if (dirpath / "README.txt").exists() and dirpath.name not in [
+                "lines_bars_and_markers",
+                "images_contours_and_fields",
+                "subplots_axes_and_figures",
+                "statistics",
+                "pie_and_polar_charts",
+                "text_labels_and_annotations",
+                "pyplots",
+                "color",
+                "shapes_and_collections",
+                "style_sheets",
+                "axes_grid1",
+                "axisartist",
+                "showcase",
+            ]
+        )
+    },
+}
+
+exhibit_syntax_style = "sphinx-gallery"
+exhibit_output_style = "sphinx-gallery"
+
+
+def autodoc_process_docstring(app, what, name, obj, options, lines):
+    lines.extend([
+        "",
+        ".. exhibit-backrefs:: py:{} {}".format(what, name),
+        "   :title: The following examples showcase the use of :py:obj:`{}`:"
+        .format(name)])
+
+
+def setup(app):
+    app.setup_extension("sphinx.ext.autodoc")
+    app.connect("autodoc-process-docstring", autodoc_process_docstring)
diff --git a/doc/contents.rst b/doc/contents.rst
@@ -1,5 +1,3 @@
-
-
 Overview
 ========
 
@@ -10,7 +8,6 @@ Overview
 
     Download `PDF <Matplotlib.pdf>`_
 
-
 .. toctree::
    :maxdepth: 2
 
@@ -22,6 +19,12 @@ Overview
    devel/index.rst
    glossary/index.rst
 
+.. toctree::
+   :hidden:
+
+   gallery/index
+   tutorials/index
+
 .. only:: html
 
   * :ref:`genindex`

diff --git a/doc/gallery/index.rst b/doc/gallery/index.rst
@@ -0,0 +1,106 @@
+.. include:: ../../examples/README.txt
+
+.. include:: ../../examples/lines_bars_and_markers/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   lines_bars_and_markers/*.py
+
+.. include:: ../../examples/images_contours_and_fields/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   images_contours_and_fields/*.py
+
+.. include:: ../../examples/subplots_axes_and_figures/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   subplots_axes_and_figures/*.py
+
+.. include:: ../../examples/statistics/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   statistics/*.py
+
+.. include:: ../../examples/pie_and_polar_charts/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   pie_features.py
+   pie_demo2.py
+   pie_and_polar_charts/*.py
+
+.. include:: ../../examples/text_labels_and_annotations/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   text_labels_and_annotations/*.py
+
+.. include:: ../../examples/pyplots/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   pyplots/*.py
+
+.. include:: ../../examples/color/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   color/color_demo.py
+   color/*.py
+
+.. include:: ../../examples/shapes_and_collections/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   shapes_and_collections/*.py
+
+.. include:: ../../examples/style_sheets/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   style_sheets/*.py
+
+.. include:: ../../examples/axes_grid1/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   axes_grid1/*.py
+
+.. include:: ../../examples/axisartist/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   axisartist/*.py
+
+.. include:: ../../examples/showcase/README.txt
+
+.. exhibit::
+   :srcdir: ../../examples
+
+   showcase/*.py
+
+.. jinja:: default
+
+   {% for subdir in examples %}
+   .. include:: ../../examples/{{ subdir }}/README.txt
+
+   .. exhibit::
+      :srcdir: ../../examples
+
+      {{ subdir }}/*.py
+   {% endfor %}