Fix search path for specs in tests

Also more verbose error message added for '_check_titles' test

Change-Id: I6a31e86bbbb05d72e5d6169efa45fe85418fe036
Closes-Bug: #1403869

specs/kilo/over-subscription-in-thin-provisioning.rst

@@ -28,7 +28,7 @@ There are a couple of problems in capacity reporting in thin provisioning:
   it is an important concept in providing thin provisioning support.
 
 Terminologies
-===============
+-------------
 
 The following terminologies will be used in this spec:
 

specs/kilo/support-iscsi-driver.rst

@@ -10,8 +10,9 @@ Support iSER driver within the ISCSIDriver flow
 
 https://blueprints.launchpad.net/cinder/+spec/support-iscsi-driver
 
-This purpose of this BP is to avoid code duplications of classes and parameters,
-and to prevent instability in the iSER driver flow, for the TGT and LIO cases.
+This purpose of this BP is to avoid code duplications of classes and
+parameters, and to prevent instability in the iSER driver flow,
+for the TGT and LIO cases.
 
 Problem description
 ===================

tests/test_titles.py

@@ -38,8 +38,9 @@ class TestTitles(testtools.TestCase):
                 titles[section['name']] = section['subtitles']
         return titles
 
-    def _check_titles(self, titles):
-        self.assertEqual(7, len(titles))
+    def _check_titles(self, spec, titles):
+        self.assertEqual(7, len(titles),
+                         "Titles count in '%s' doesn't match expected" % spec)
         problem = 'Problem description'
         self.assertIn(problem, titles)
 
@@ -89,8 +90,19 @@ class TestTitles(testtools.TestCase):
             (len(matches), tpl))
 
     def test_template(self):
-        release = ['juno', 'kilo']
-        files = ['specs/template.rst'] + glob.glob("specs/%s/*/*" % release)
+        releases = ['juno', 'kilo']
+
+        files = ['specs/template.rst']
+
+        # NOTE (e0ne): We don't check specs in 'api' directory because
+        # they don't match template.rts. Uncomment code below it you want
+        # to test them.
+        # files.extend(glob.glob('specs/api/*/*'))
+
+        for release in releases:
+            specs = glob.glob('specs/%s/*' % release)
+            files.extend(specs)
+
         for filename in files:
             self.assertTrue(filename.endswith(".rst"),
                             "spec's file must use 'rst' extension.")
@@ -99,6 +111,6 @@ class TestTitles(testtools.TestCase):
 
             spec = docutils.core.publish_doctree(data)
             titles = self._get_titles(spec)
-            self._check_titles(titles)
+            self._check_titles(filename, titles)
             self._check_lines_wrapping(filename, data)
             self._check_no_cr(filename, data)