Fix raise section in docstrings

The correct format is:
    :raises Exception: conditions

This patch fix all docstrings across the project and
add hacking rule to check it.

Change-Id: I40cc20f8d555082e284c1683522932aaa68f575c
Closes-Bug: 1470901

rally/plugins/openstack/scenarios/heat/utils.py

@@ -331,7 +331,7 @@ class HeatScenario(scenario.OpenStackScenario):
 
         :param stack: stack to call a webhook on
         :param output_key: The name of the output to get the URL from
-        :raises: InvalidConfigException if the output key is not found
+        :raises InvalidConfigException: if the output key is not found
         """
         url = None
         for output in stack.outputs:

tests/hacking/README.rst

@@ -27,3 +27,4 @@ Rally Specific Commandments
 * [N351] - Ensure that data structs (i.e Lists and Dicts) are declared literally rather than using constructors
 * [N352] - Ensure that string formatting only uses a mapping if multiple mapping keys are used.
 * [N353] - Ensure that unicode() function is not uset because of absence in py3
+* [N354] - Ensure that ``:raises: Exception`` is not used

tests/hacking/checks.py

@@ -59,6 +59,8 @@ re_str_format = re.compile(r"""
 [hLl]?       # optional length modifier
 [A-z%]       # conversion modifier
 """, re.X)
+re_raises = re.compile(
+    r"\s:raise[^s] *.*$|\s:raises *:.*$|\s:raises *[^:]+$")
 
 
 def skip_ignored_lines(func):
@@ -441,6 +443,20 @@ def check_using_unicode(logical_line, filename):
                   "use 'six.text_type' instead.")
 
 
+def check_raises(physical_line, filename):
+    """Check raises usage
+
+    N354
+    """
+
+    ignored_files = ["./tests/unit/test_hacking.py",
+                     "./tests/hacking/checks.py"]
+    if filename not in ignored_files:
+        if re_raises.search(physical_line):
+            return (0, "N354 ':Please use ':raises Exception: conditions' "
+                       "in docstrings.")
+
+
 def factory(register):
     register(check_assert_methods_from_mock)
     register(check_import_of_logging)
@@ -457,3 +473,4 @@ def factory(register):
     register(check_no_constructor_data_struct)
     register(check_dict_formatting_in_string)
     register(check_using_unicode)
+    register(check_raises)

tests/unit/fakes.py

@@ -68,7 +68,7 @@ def setup_dict(data, required=None, defaults=None):
     :param required: list, mandatory keys to check
     :param defaults: dict, default data
     :returns: dict, with all keys set
-    :raises: IndexError, ValueError
+    :raises IndexError, ValueError: If input data is incorrect
     """
     required = required or []
     for i in set(required) - set(data):

tests/unit/test_hacking.py

@@ -319,3 +319,12 @@ class HackingTestCase(test.TestCase):
             "text = process(unicode('sometext'))", "fakefile")
         self.assertIsNotNone(next(checkres))
         self.assertEqual([], list(checkres))
+
+    def test_check_raises(self):
+        checkres = checks.check_raises(
+            "text = :raises: Exception if conditions", "fakefile")
+        self.assertIsNotNone(checkres)
+
+        checkres = checks.check_raises(
+            "text = :raises Exception: if conditions", "fakefile")
+        self.assertIsNone(checkres)