Translates from api_calls dictionary [returned from get_api_calls()]
    into a markdown spec (i.e., docs/api-specs.md)

    $ python -c "from api.utils import *; f = open('/tmp/foo', 'w'); write_markdown_spec(f, get_api_calls('api/api_v1.md')); f.close()"

def write_markdown_spec(f_out, api_calls):
    """
    Translates from api_calls dictionary [returned from get_api_calls()]
    into a markdown spec (i.e., docs/api-specs.md)

    $ python -c "from api.utils import *; f = open('/tmp/foo', 'w'); write_markdown_spec(f, get_api_calls('api/api_v1.md')); f.close()"
    """
    groups = OrderedDict()
    
    for api_obj in api_calls:
        obj = {}
        obj["Method"] = api_obj["title"]
        obj["API Call"] = "{} {}".format(api_obj["method"],
                                         api_obj["path_template"])
        obj["Grouping"] = api_obj["grouping"]
        obj["Notes"] = api_obj["notes"] if "notes" in api_obj else ""
        obj["API Family"] = api_obj["family"] if "family" in api_obj else "-"
        obj["Subgroup"] = api_obj["subgrouping"] if "subgrouping" in api_obj else ""
        
        if obj["Grouping"] not in groups:
            groups[obj["Grouping"]] = MarkdownGroup()
        groups[obj["Grouping"]].add_to_group(obj, obj["Subgroup"])

        if "grouping_note" in api_obj:
            groups[obj["Grouping"]].notes = api_obj["grouping_note"]

    row_headers = ["Method", "API Call", "API Family", "Notes"]


    f_out.write("# Blockstack Specifications\n\n")
    for gname, g in groups.items():
        f_out.write("## {}\n\n".format(gname))
        for sg_name, sg in g.subgroups.items():
            if len(sg_name) > 0:
                f_out.write("### {}\n\n".format(sg_name))
            f_out.write("| {} |\n".format(" | ".join(row_headers)))
            f_out.write("| {} |\n".format(" | ".join(["-------------" for i in row_headers])))
            for item in sg:
                f_out.write("| {} |\n".format(" | ".join(
                    [item[k] for k in row_headers])))
            f_out.write("\n")
        if g.notes:
            f_out.write("#### {}\n\n".format(g.notes))