Add warning for invalid parameters

Currently, when a parameter is formatted wrong sphinx dies with a
cryptic error message:

    AttributeError: 'str' object has no attribute 'items'

This happens because the parameter is not recognized as dict.

This patch adds a check that ensures parameters are formatted correctly
by verifying that they're dicts.

Change-Id: I0140336cdcd9fd1d356d1fa50fd8dd15790ef8bd

os_api_ref/__init__.py

@@ -265,6 +265,15 @@ class RestParametersDirective(Table):
         # self.app.info("Lookup table looks like %s" % lookup)
         new_content = list()
         for paramlist in parsed:
+            if not isinstance(paramlist, dict):
+                self.env.warn(
+                    "%s:%s" % (
+                        self.state_machine.node.source,
+                        self.state_machine.node.line),
+                    ("Invalid parameter definition ``%s``. Expected "
+                     "format: ``name: reference``. "
+                     " Skipping." % paramlist))
+                continue
             for name, ref in paramlist.items():
                 if ref in lookup:
                     new_content.append((name, lookup[ref]))

os_api_ref/tests/examples/warnings/index.rst

@@ -13,3 +13,4 @@ I am text, hear me roar!
    - name: name
    - name: lookup_key_name
    - name: name_1
+   - invalid_name

os_api_ref/tests/test_warnings.py

@@ -66,3 +66,10 @@ class TestWarnings(base.TestCase):
              + " ('required', True)]). "
              + "'NoneType' object has no attribute 'split'\n"),
             self.warning)
+
+    def test_invalid_parameter_definition(self):
+        """Warning when parameter definition is invalid."""
+        self.assertIn(
+            ("WARNING: Invalid parameter definition ``invalid_name``. "
+             + "Expected format: ``name: reference``. "),
+            self.warning)