support function exception desc (#45)

* support function exception desc

* fix code review comments

docfx_yaml/extension.py

@@ -459,6 +459,10 @@ def convert_module_to_package_if_needed(obj):
                     if 'example' in obj['syntax'] and obj['syntax']['example']:
                         obj.setdefault('example', []).append(obj['syntax'].pop('example'))
 
+                    # Raise up exceptions
+                    if 'exceptions' in obj['syntax'] and obj['syntax']['exceptions']:
+                        obj['exceptions'] = obj['syntax'].pop('exceptions')
+
                     # add content of temp list 'enum_attribute' to children and yaml_data
                     if 'enum_attribute' in obj['syntax'] and obj['syntax']['enum_attribute']:
                         enum_attribute = obj['syntax'].pop('enum_attribute')

docfx_yaml/monkeypatch.py

@@ -138,7 +138,7 @@ def patch_docfields(app):
 
     transform_node = partial(_transform_node, app)
 
-    def get_data_structure(entries, types):
+    def get_data_structure(entries, types, field_object):
         """
         Get a proper docfx YAML data structure from the entries & types
         """
@@ -165,6 +165,29 @@ def transform_para(para_field):
             else:
                 return para_field.astext()
 
+        def extract_exception_desc(field_object):
+            ret = []
+            if len(field_object) > 0:
+                for field in field_object:
+                    if 'field_name' == field[0].tagname and field[0].astext() == 'Raises':
+                        assert field[1].tagname == 'field_body'
+                        field_body = field[1]
+
+                        children = [n for n in field_body
+                            if not isinstance(n, nodes.Invisible)]
+
+                        for child in children:
+                            if isinstance (child, nodes.paragraph):
+                                pending_xref_index = child.first_child_matching_class(addnodes.pending_xref)
+                                if pending_xref_index is not None:
+                                    pending_xref = child[pending_xref_index]
+                                    raise_type_index = pending_xref.first_child_matching_class(nodes.literal)
+                                    if raise_type_index is not None:
+                                        raise_type = pending_xref[raise_type_index]
+                                        ret.append({'type': pending_xref['reftarget'], 'desc': raise_type.astext()})
+
+            return ret
+
         for entry in entries:
             if isinstance(entry, nodes.field):
                 # pass-through old field
@@ -206,6 +229,13 @@ def transform_para(para_field):
                             _data = make_param(_id=_id, _type=_type, _description=_description)
                             data['variables'].append(_data)
 
+                    ret_list = extract_exception_desc(field_object)
+                    for ret in ret_list:
+                        data.setdefault('exceptions', []).append({
+                            'type': ret['type'],
+                            'description': ret['desc']
+                        })
+
         return data
 
 
@@ -256,7 +286,7 @@ def transform_all(self, node):
                     continue
                 elif isinstance(child, nodes.field_list):
                     (entries, types) = _hacked_transform(self.typemap, child)
-                    _data = get_data_structure(entries, types)
+                    _data = get_data_structure(entries, types, child)
                     data.update(_data)
                 elif isinstance(child, addnodes.seealso):
                     data['seealso'] = transform_node(child)