2 # Copyright (C) The Arvados Authors. All rights reserved.
4 # SPDX-License-Identifier: CC-BY-SA-3.0
6 # gen_api_method_docs.py
8 # Generate docs for Arvados methods.
10 # This script will retrieve the discovery document at
11 # https://localhost:9900/discovery/v1/apis/arvados/v1/rest
12 # and will generate Textile documentation files in the current
22 p = argparse.ArgumentParser(description='Generate Arvados API method documentation.')
24 p.add_argument('--host',
27 help="The hostname or IP address of the API server")
29 p.add_argument('--port',
32 help="The port of the API server")
34 p.add_argument('--output-dir',
37 help="Directory in which to write output files.")
41 api_url = 'https://{host}:{port}/discovery/v1/apis/arvados/v1/rest'.format(**vars(args))
43 r = requests.get(api_url, verify=False)
44 if r.status_code != 200:
45 raise Exception('Bad status code %d: %s' % (r.status_code, r.text))
47 if 'application/json' not in r.headers.get('content-type', ''):
48 raise Exception('Unexpected content type: %s: %s' %
49 (r.headers.get('content-type', ''), r.text))
54 for resource in sorted(api[u'resources']):
55 resource_num = resource_num + 1
56 out_fname = os.path.join(args.output_dir, resource + '.textile')
57 if os.path.exists(out_fname):
58 backup_name = out_fname + '.old'
60 os.rename(out_fname, backup_name)
62 print "WARNING: could not back up {1} as {2}: {3}".format(
63 out_fname, backup_name, e)
64 outf = open(out_fname, 'w')
70 navorder: {resource_num}
75 Required arguments are displayed in %{{background:#ccffcc}}green%.
77 """.format(resource_num=resource_num, resource=resource))
79 methods = api['resources'][resource]['methods']
80 for method in sorted(methods.keys()):
81 methodinfo = methods[method]
90 table(table table-bordered table-condensed).
91 |_. Argument |_. Type |_. Description |_. Location |_. Example |
93 method=method, description=methodinfo['description']))
97 for param, paraminfo in methodinfo['parameters'].iteritems():
98 paraminfo.setdefault(u'description', '')
99 paraminfo.setdefault(u'location', '')
101 if paraminfo.get('minimum', '') or paraminfo.get('maximum', ''):
102 limit = "range {0}-{1}".format(
103 paraminfo.get('minimum', ''),
104 paraminfo.get('maximum', 'unlimited'))
105 if paraminfo.get('default', ''):
108 limit = limit + 'default %d' % paraminfo['default']
110 paraminfo['type'] = '{0} ({1})'.format(
111 paraminfo['type'], limit)
113 row = "|{param}|{type}|{description}|{location}||\n".format(
114 param=param, **paraminfo)
115 if paraminfo.get('required', False):
118 notrequired.append(row)
120 for row in sorted(required):
121 outf.write("{background:#ccffcc}." + row)
122 for row in sorted(notrequired):
125 # pprint.pprint(methodinfo)
128 print "wrote ", out_fname