Merge pull request #74 from GaelVaroquaux/sort_examples

ENH: sort the examples from shortest to longest

sphinx_gallery/gen_rst.py

@@ -373,20 +373,27 @@ def generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs):
         os.makedirs(target_dir)
     sorted_listdir = [fname for fname in sorted(os.listdir(src_dir))
                       if fname.endswith('.py')]
+    entries_text = []
     for fname in sorted_listdir:
-        generate_file_rst(fname, target_dir, src_dir, gallery_conf)
+        amount_of_code = generate_file_rst(fname, target_dir, src_dir,
+                                           gallery_conf)
         new_fname = os.path.join(src_dir, fname)
         intro = extract_intro(new_fname)
         write_backreferences(seen_backrefs, gallery_conf,
                              target_dir, fname, intro)
-
-        fhindex += _thumbnail_div(target_dir, fname, intro)
-        fhindex += """
+        this_entry =  _thumbnail_div(target_dir, fname, intro) + """
 
 .. toctree::
    :hidden:
 
    /%s/%s\n""" % (target_dir, fname[:-3])
+        entries_text.append((amount_of_code, this_entry))
+
+    # sort to have the smallest entries in the beginning
+    entries_text.sort()
+
+    for _, entry_text in entries_text:
+        fhindex += entry_text
 
     # clear at the end of the section
     fhindex += """.. raw:: html\n
@@ -457,7 +464,11 @@ def execute_script(code_block, example_globals, image_path, fig_count,
 
 
 def generate_file_rst(fname, target_dir, src_dir, gallery_conf):
-    """ Generate the rst file for a given example."""
+    """ Generate the rst file for a given example.
+
+        Returns the amout of code (in characters) of the corresponding
+        files.
+    """
 
     src_file = os.path.join(src_dir, fname)
     example_file = os.path.join(target_dir, fname)
@@ -471,11 +482,16 @@ def generate_file_rst(fname, target_dir, src_dir, gallery_conf):
     image_fname = 'sphx_glr_' + base_image_name + '_{0:03}.png'
     image_path = os.path.join(image_dir, image_fname)
 
+    script_blocks = split_code_and_text_blocks(example_file)
+
+    amount_of_code = sum([len(bcontent)
+                         for blabel, bcontent in script_blocks
+                         if blabel == 'code'])
+
     if _plots_are_current(src_file, image_path):
-        return
+        return amount_of_code
 
     time_elapsed = 0
-    script_blocks = split_code_and_text_blocks(example_file)
 
     ref_fname = example_file.replace(os.path.sep, '_')
     example_rst = """\n\n.. _sphx_glr_{0}:\n\n""".format(ref_fname)
@@ -523,3 +539,4 @@ def generate_file_rst(fname, target_dir, src_dir, gallery_conf):
     with open(os.path.join(target_dir, base_image_name + '.rst'), 'w') as f:
         example_rst += CODE_DOWNLOAD.format(time_m, time_s, fname)
         f.write(example_rst)
+    return amount_of_code