18794: Merge branch 'main'
[arvados.git] / doc / gen_api_method_docs.py
1 #! /usr/bin/env python
2 # Copyright (C) The Arvados Authors. All rights reserved.
3 #
4 # SPDX-License-Identifier: CC-BY-SA-3.0
5
6 # gen_api_method_docs.py
7 #
8 # Generate docs for Arvados methods.
9 #
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
13 # directory.
14
15 import argparse
16 import pprint
17 import re
18 import requests
19 import os
20 import sys #debugging
21
22 p = argparse.ArgumentParser(description='Generate Arvados API method documentation.')
23
24 p.add_argument('--host',
25                type=str,
26                default='localhost',
27                help="The hostname or IP address of the API server")
28
29 p.add_argument('--port',
30                type=int,
31                default=9900,
32                help="The port of the API server")
33
34 p.add_argument('--output-dir',
35                type=str,
36                default='.',
37                help="Directory in which to write output files.")
38
39 args = p.parse_args()
40
41 api_url = 'https://{host}:{port}/discovery/v1/apis/arvados/v1/rest'.format(**vars(args))
42
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))
46
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))
50
51 api = r.json()
52
53 resource_num = 0
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'
59         try:
60             os.rename(out_fname, backup_name)
61         except OSError as e:
62             print "WARNING: could not back up {0} as {1}: {2}".format(
63                 out_fname, backup_name, e)
64     outf = open(out_fname, 'w')
65     outf.write(
66 """---
67 navsection: api
68 navmenu: API Methods
69 title: "{resource}"
70 navorder: {resource_num}
71 ---
72
73 h1. {resource}
74
75 Required arguments are displayed in %{{background:#ccffcc}}green%.
76
77 """.format(resource_num=resource_num, resource=resource))
78
79     methods = api['resources'][resource]['methods']
80     for method in sorted(methods.keys()):
81         methodinfo = methods[method]
82         outf.write(
83 """
84 h2. {method}
85
86 {description}
87
88 Arguments:
89
90 table(table table-bordered table-condensed).
91 |_. Argument |_. Type |_. Description |_. Location |_. Example |
92 """.format(
93     method=method, description=methodinfo['description']))
94
95         required = []
96         notrequired = []
97         for param, paraminfo in methodinfo['parameters'].iteritems():
98             paraminfo.setdefault(u'description', '')
99             paraminfo.setdefault(u'location', '')
100             limit = ''
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', ''):
106                 if limit:
107                     limit = limit + '; '
108                 limit = limit + 'default %d' % paraminfo['default']
109             if limit:
110                 paraminfo['type'] = '{0} ({1})'.format(
111                     paraminfo['type'], limit)
112
113             row = "|{param}|{type}|{description}|{location}||\n".format(
114                 param=param, **paraminfo)
115             if paraminfo.get('required', False):
116                 required.append(row)
117             else:
118                 notrequired.append(row)
119
120         for row in sorted(required):
121             outf.write("{background:#ccffcc}." + row)
122         for row in sorted(notrequired):
123             outf.write(row)
124
125         # pprint.pprint(methodinfo)
126
127     outf.close()
128     print "wrote ", out_fname
129
130