'Convert field lists with known keys inside the description content into
better-looking equivalents.'

def handle_doc_fields(self, node):

    for child in node.children:
        if (not isinstance(child, nodes.field_list)):
            continue
        params = []
        pfield = None
        param_nodes = {}
        param_types = {}
        new_list = nodes.field_list()
        for field in child:
            (fname, fbody) = field
            try:
                (typ, obj) = fname.astext().split(None, 1)
                typdesc = _(self.doc_fields_with_arg[typ])
                if _is_only_paragraph(fbody):
                    children = fbody.children[0].children
                else:
                    children = fbody.children
                if (typdesc == '%param'):
                    if (not params):
                        pfield = nodes.field()
                        new_list += pfield
                    dlitem = nodes.list_item()
                    dlpar = nodes.paragraph()
                    dlpar += nodes.emphasis(obj, obj)
                    dlpar += nodes.Text('    --    ', '    --    ')
                    dlpar += children
                    param_nodes[obj] = dlpar
                    dlitem += dlpar
                    params.append(dlitem)
                elif (typdesc == '%type'):
                    typenodes = fbody.children
                    if _is_only_paragraph(fbody):
                        typenodes = (([nodes.Text('    (')] + typenodes[0].children) + [nodes.Text(')')])
                    param_types[obj] = typenodes
                else:
                    fieldname = (typdesc + '    ')
                    nfield = nodes.field()
                    nfieldname = nodes.field_name(fieldname, fieldname)
                    nfield += nfieldname
                    node = nfieldname
                    if (typ in self.doc_fields_with_linked_arg):
                        node = addnodes.pending_xref(obj, reftype='obj', refcaption=False, reftarget=obj, modname=self.env.currmodule, classname=self.env.currclass)
                        nfieldname += node
                    node += nodes.Text(obj, obj)
                    nfield += nodes.field_body()
                    nfield[1] += fbody.children
                    new_list += nfield
            except (KeyError, ValueError):
                fnametext = fname.astext()
                try:
                    typ = _(self.doc_fields_without_arg[fnametext])
                except KeyError:
                    typ = fnametext.capitalize()
                fname[0] = nodes.Text(typ)
                new_list += field
        if params:
            if (len(params) == 1):
                pfield += nodes.field_name('', _('Parameter'))
                pfield += nodes.field_body()
                pfield[1] += params[0][0]
            else:
                pfield += nodes.field_name('', _('Parameters'))
                pfield += nodes.field_body()
                pfield[1] += nodes.bullet_list()
                pfield[1][0].extend(params)
        for (param, type) in param_types.iteritems():
            if (param in param_nodes):
                param_nodes[param][1:1] = type
        child.replace_self(new_list)
