Use get_docstring_and_rest to get example tooltip

rather than split_code_and_text_blocks since we only need the docstring.
Also rename variable and improve error message

sphinxgallery/gen_rst.py

@@ -196,20 +196,21 @@ def text2string(content):
 def extract_intro(filename):
     """ Extract the first paragraph of module-level docstring. max:95 char"""
 
-    first_text = split_code_and_text_blocks(filename)[0][-1]
-
-    paragraphs = first_text.split('\n\n')
-    if len(first_text) > 1:
-        first_par = re.sub('\n', ' ', paragraphs[1])
-        first_par = ((first_par[:95] + '...')
-                     if len(first_par) > 95 else first_par)
+    docstring, _ = get_docstring_and_rest(filename)
+
+    # lstrip is just in case docstring has a '\n\n' at the beginning
+    paragraphs = docstring.lstrip().split('\n\n')
+    if len(paragraphs) > 1:
+        first_paragraph = re.sub('\n', ' ', paragraphs[1])
+        first_paragraph = (first_paragraph[:95] + '...'
+                           if len(first_paragraph) > 95 else first_paragraph)
     else:
-        raise ValueError("Missing first paragraph."
-                         "Please check the layout of your"
-                         " example file:\n {}\n and make sure"
-                         " it's correct.".format(filename))
+        raise ValueError(
+            "Example docstring should have a header for the example title "
+            "and at least a paragraph explaining what the example is about. "
+            "Please check the example file:\n {}\n".format(filename))
 
-    return first_par
+    return first_paragraph
 
 
 def _plots_are_current(src_file, image_file):

sphinxgallery/tests/test_gen_rst.py

@@ -5,8 +5,10 @@
 Testing the rst files generator
 """
 from __future__ import division, absolute_import, print_function
+import tempfile
+
 import sphinxgallery.gen_rst as sg
-from nose.tools import assert_equals
+from nose.tools import assert_equals, assert_false
 import ast
 
 
@@ -38,3 +40,25 @@ def test_codestr2rst():
 
     print("hello world")"""
     assert_equals(reference, output)
+
+
+def test_extract_intro():
+    with tempfile.NamedTemporaryFile() as f:
+        f.write(b'\n'.join([b'"""'
+                            b'Docstring header',
+                            b'================',
+                            b'',
+                            b'This is the explanation of the example'
+                            b'which goes on and on',
+                            b'', b'',
+                            b'And this is a second paragraph',
+                            b'"""']))
+
+        f.flush()
+
+        result = sg.extract_intro(f.name)
+        assert_false('Docstring' in result)
+        assert_equals(
+            result,
+            'This is the explanation of the example which goes on and on')
+        assert_false('second paragraph' in result)