[MAINT] update to sphinx-gallery v0.1.2

Author: Titan-C

doc/sphinxext/sphinx_gallery/__init__.py

@@ -5,7 +5,7 @@
 
 """
 import os
-__version__ = '0.1.1'
+__version__ = '0.1.2'
 
 
 def glr_path_static():

doc/sphinxext/sphinx_gallery/gen_gallery.py

@@ -20,6 +20,7 @@
 
 
 def clean_gallery_out(build_dir):
+    """Deletes images under the sphx_glr namespace in the build directory"""
     # Sphinx hack: sphinx copies generated images to the build directory
     #  each time the docs are made.  If the desired image name already
     #  exists, it appends a digit to prevent overwrites.  The problem is,
@@ -30,10 +31,11 @@ def clean_gallery_out(build_dir):
     #  was no response: http://osdir.com/ml/sphinx-dev/2011-02/msg00123.html
     #
     # The following is a hack that prevents this behavior by clearing the
-    #  image build directory each time the docs are built.  If sphinx
-    #  changes their layout between versions, this will not work (though
-    #  it should probably not cause a crash).  Tested successfully
-    #  on Sphinx 1.0.7
+    #  image build directory from gallery images each time the docs are built.
+    #  If sphinx changes their layout between versions, this will not
+    #  work (though it should probably not cause a crash).
+    # Tested successfully on Sphinx 1.0.7
+
     build_image_dir = os.path.join(build_dir, '_images')
     if os.path.exists(build_image_dir):
         filelist = os.listdir(build_image_dir)
@@ -101,11 +103,26 @@ def generate_gallery_rst(app):
         fhindex.flush()
 
 
+def touch_empty_backreferences(app, what, name, obj, options, lines):
+    """Generate empty back-reference example files
+
+    This avoids inclusion errors/warnings if there are no gallery
+    examples for a class / module that is being parsed by autodoc"""
+
+    examples_path = os.path.join(app.srcdir,
+                                 app.config.sphinx_gallery_conf["mod_example_dir"],
+                                 "%s.examples" % name)
+
+    if not os.path.exists(examples_path):
+        # touch file
+        open(examples_path, 'w').close()
+
+
 gallery_conf = {
     'filename_pattern': re.escape(os.sep) + 'plot',
     'examples_dirs': '../examples',
     'gallery_dirs': 'auto_examples',
-    'mod_example_dir': 'modules/generated',
+    'mod_example_dir': os.path.join('modules', 'generated'),
     'doc_module': (),
     'reference_url': {},
 }
@@ -118,6 +135,9 @@ def setup(app):
     app.add_config_value('sphinx_gallery_conf', gallery_conf, 'html')
     app.add_stylesheet('gallery.css')
 
+    if 'sphinx.ext.autodoc' in app._extensions:
+        app.connect('autodoc-process-docstring', touch_empty_backreferences)
+
     app.connect('builder-inited', generate_gallery_rst)
 
     app.connect('build-finished', embed_code_links)

doc/sphinxext/sphinx_gallery/gen_rst.py

@@ -553,13 +553,18 @@ def generate_file_rst(fname, target_dir, src_dir, gallery_conf):
 
     filename_pattern = gallery_conf.get('filename_pattern')
     if re.search(filename_pattern, src_file) and gallery_conf['plot_gallery']:
-        # A lot of examples contains 'print(__doc__)' for example in
-        # scikit-learn so that running the example prints some useful
-        # information. Because the docstring has been separated from
-        # the code blocks in sphinx-gallery, __doc__ is actually
-        # __builtin__.__doc__ in the execution context and we do not
-        # want to print it
-        example_globals = {'__doc__': ''}
+        example_globals = {
+            # A lot of examples contains 'print(__doc__)' for example in
+            # scikit-learn so that running the example prints some useful
+            # information. Because the docstring has been separated from
+            # the code blocks in sphinx-gallery, __doc__ is actually
+            # __builtin__.__doc__ in the execution context and we do not
+            # want to print it
+            '__doc__': '',
+            # Examples may contain if __name__ == '__main__' guards
+            # for in example scikit-learn if the example uses multiprocessing
+            '__name__': '__main__'}
+
         fig_count = 0
         # A simple example has two blocks: one for the
         # example introduction/explanation and one for the code
@@ -581,6 +586,9 @@ def generate_file_rst(fname, target_dir, src_dir, gallery_conf):
                     example_rst += code_output
                 else:
                     example_rst += code_output
+                    if 'sphx-glr-script-out' in code_output:
+                        # Add some vertical space after output
+                        example_rst += "\n\n|\n\n"
                     example_rst += codestr2rst(bcontent) + '\n'
 
             else: