doc/gen_api_method_docs.py

   1 #! /usr/bin/env python
   2
   3 # gen_api_method_docs.py
   4 #
   5 # Generate docs for Arvados methods.
   6 #
   7 # This script will retrieve the discovery document at
   8 # https://localhost:9900/discovery/v1/apis/arvados/v1/rest
   9 # and will generate Textile documentation files in the current
  10 # directory.
  11
  12 import requests
  13 import re
  14 import os
  15 import pprint
  16
  17 r = requests.get('https://localhost:9900/discovery/v1/apis/arvados/v1/rest',
  18                  verify=False)
  19 if r.status_code != 200:
  20     raise Exception('Bad status code %d: %s' % (r.status_code, r.text))
  21
  22 if 'application/json' not in r.headers.get('content-type', ''):
  23     raise Exception('Unexpected content type: %s: %s' %
  24                     (r.headers.get('content-type', ''), r.text))
  25
  26 api = r.json
  27
  28 resource_num = 0
  29 for resource in sorted(api[u'resources']):
  30     resource_num = resource_num + 1
  31     out_fname = resource + '.textile'
  32     if os.path.exists(out_fname):
  33         print "PATH EXISTS ", out_fname
  34         next
  35     outf = open(out_fname, 'w')
  36     outf.write(
  37 """---
  38 layout: default
  39 navsection: api
  40 navmenu: API Methods
  41 title: "{resource}"
  42 navorder: {resource_num}
  43 ---
  44
  45 h1. {resource}
  46
  47 Required arguments are displayed in %{{background:#ccffcc}}green%.
  48
  49 """.format(resource_num=resource_num, resource=resource))
  50
  51     methods = api['resources'][resource]['methods']
  52     for method in sorted(methods.keys()):
  53         methodinfo = methods[method]
  54         outf.write(
  55 """
  56 h2. {method}
  57
  58 {description}
  59
  60 Arguments:
  61
  62 table(table table-bordered table-condensed).
  63 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  64 """.format(
  65     method=method, description=methodinfo['description']))
  66
  67         required = []
  68         notrequired = []
  69         for param, paraminfo in methodinfo['parameters'].iteritems():
  70             paraminfo.setdefault(u'description', '')
  71             paraminfo.setdefault(u'location', '')
  72             limit = ''
  73             if paraminfo.get('minimum', '') or paraminfo.get('maximum', ''):
  74                 limit = "range {0}-{1}".format(
  75                     paraminfo.get('minimum', ''),
  76                     paraminfo.get('maximum', 'unlimited'))
  77             if paraminfo.get('default', ''):
  78                 if limit:
  79                     limit = limit + '; '
  80                 limit = limit + 'default %d' % paraminfo['default']
  81             if limit:
  82                 paraminfo['type'] = '{0} ({1})'.format(
  83                     paraminfo['type'], limit)
  84
  85             row = "|{param}|{type}|{description}|{location}||\n".format(
  86                 param=param, **paraminfo)
  87             if paraminfo.get('required', False):
  88                 required.append(row)
  89             else:
  90                 notrequired.append(row)
  91
  92         for row in sorted(required):
  93             outf.write("{background:#ccffcc}." + row)
  94         for row in sorted(notrequired):
  95             outf.write(row)
  96
  97         # pprint.pprint(methodinfo)
  98
  99     outf.close()
 100     print "wrote ", out_fname
 101
 102